Introduction

The error "image could not be accessed on a registry to record its digest" occurs when docker service update cannot reach the container registry to verify and record the image digest. Docker Swarm resolves image tags to their SHA256 digest during service updates to ensure all nodes pull the exact same image. If the swarm manager cannot contact the registry — due to authentication issues, network problems, or the image not existing — this error is thrown. The fix depends on whether the issue is credentials, network, or the image reference itself.

The Error

1$ docker service update --image myregistry.com/myapp:v2 myservice
2
3image myregistry.com/myapp:v2 could not be accessed on a registry to record its digest.
4Each node will access myregistry.com/myapp:v2 independently,
5possibly leading to different nodes running different versions of the image.

Docker Swarm tries to resolve the tag to a digest (e.g., sha256:abc123...) so every node pulls the same bytes. When it cannot reach the registry, it falls back to using the tag — but different nodes might get different images if the tag was updated between pulls.

Fix 1: Log In to the Registry

1# Log in on the swarm manager node
2docker login myregistry.com
3
4# For AWS ECR
5aws ecr get-login-password --region us-east-1 | \
6  docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com
7
8# For Google Container Registry
9gcloud auth configure-docker
10
11# Verify login
12docker pull myregistry.com/myapp:v2
13
14# Now update the service
15docker service update --image myregistry.com/myapp:v2 myservice

The swarm manager needs registry credentials to resolve the digest. docker login stores credentials that Docker Swarm uses for digest resolution and image pulls.

Fix 2: Use --with-registry-auth

1# Pass registry credentials to all swarm nodes
2docker service update \
3  --with-registry-auth \
4  --image myregistry.com/myapp:v2 \
5  myservice
6
7# Same flag works with docker service create
8docker service create \
9  --with-registry-auth \
10  --name myservice \
11  --replicas 3 \
12  myregistry.com/myapp:v2

--with-registry-auth forwards the manager's registry credentials to worker nodes. Without it, worker nodes may not be able to pull the image from a private registry.

Fix 3: Use the Full Digest Instead of Tag

1# Get the digest
2docker inspect --format='{{index .RepoDigests 0}}' myregistry.com/myapp:v2
3# Output: myregistry.com/myapp@sha256:abc123def456...
4
5# Update using the digest directly — no registry lookup needed
6docker service update \
7  --image myregistry.com/myapp@sha256:abc123def456789 \
8  myservice

Using the full digest bypasses the tag-to-digest resolution step. Docker does not need to contact the registry to verify the digest — it already knows the exact image to pull.

Fix 4: Use --resolve-image never

1# Skip digest resolution entirely
2docker service update \
3  --resolve-image never \
4  --image myregistry.com/myapp:v2 \
5  myservice

--resolve-image never tells Docker Swarm to skip the registry lookup and use the tag as-is. This silences the error but means different nodes might pull different images if the tag is updated between pulls. Use with caution in production.

Fix 5: Network and DNS Issues

1# Check if the manager can reach the registry
2curl -v https://myregistry.com/v2/
3
4# Check DNS resolution
5nslookup myregistry.com
6dig myregistry.com
7
8# Check if Docker daemon can reach the registry
9docker pull myregistry.com/myapp:v2
10
11# Check proxy settings
12echo $HTTP_PROXY $HTTPS_PROXY $NO_PROXY
13
14# Docker daemon proxy (systemd)
15cat /etc/systemd/system/docker.service.d/http-proxy.conf

If the manager node is behind a firewall or proxy, Docker may not reach the registry. Configure proxy settings in the Docker daemon or ensure the registry is accessible from the manager network.

Fix 6: Self-Signed Certificate Registry

1# Add the CA certificate to Docker's trusted certs
2sudo mkdir -p /etc/docker/certs.d/myregistry.com:5000/
3sudo cp ca.crt /etc/docker/certs.d/myregistry.com:5000/ca.crt
4
5# Or configure insecure registry (not recommended for production)
6# In /etc/docker/daemon.json
7{
8  "insecure-registries": ["myregistry.com:5000"]
9}
10
11# Restart Docker daemon
12sudo systemctl restart docker

If your private registry uses a self-signed certificate, Docker rejects the TLS connection by default. Add the CA certificate to Docker's trusted store or configure the registry as insecure for development.

Diagnosing the Issue

1# Check service status
2docker service ps myservice --no-trunc
3
4# Check for image pull errors on specific nodes
5docker service ps myservice --filter "desired-state=running" --format "{{.Node}} {{.Error}}"
6
7# Inspect the service to see current image
8docker service inspect myservice --format '{{.Spec.TaskTemplate.ContainerSpec.Image}}'
9
10# Check Docker daemon logs for registry errors
11journalctl -u docker.service --since "10 minutes ago" | grep -i registry

Common Pitfalls

• Forgetting --with-registry-auth: The swarm manager may have credentials, but worker nodes do not automatically receive them. Without --with-registry-auth, workers cannot pull from private registries even if the manager can.
• Expired ECR/GCR tokens: AWS ECR tokens expire after 12 hours and GCR tokens can expire too. Automate re-authentication in CI/CD pipelines or use credential helpers (docker-credential-ecr-login) that refresh automatically.
• Using latest tag: The latest tag is mutable — it points to different images over time. Combined with the digest resolution error, different nodes may run different versions. Always use specific version tags or digests.
• Registry behind VPN not accessible from all nodes: If the registry is on a private network, ensure all swarm nodes (manager and workers) can reach it. The manager resolves the digest, but workers need to pull the image independently.
• Docker daemon proxy not configured: Even if shell environment variables (HTTP_PROXY) are set, the Docker daemon runs as a separate systemd service and needs proxy configuration in /etc/systemd/system/docker.service.d/. Shell variables do not propagate to the daemon.

Summary

• The error occurs when Docker Swarm cannot reach the registry to resolve an image tag to a digest
• Log in with docker login on the manager node and use --with-registry-auth to forward credentials to workers
• Use full image digests (@sha256:...) to skip tag resolution entirely
• Use --resolve-image never as a last resort to bypass digest resolution
• Check network connectivity, DNS, proxy settings, and TLS certificates on all swarm nodes
• Automate credential refresh for registries with expiring tokens (ECR, GCR)