docker: invalid reference format

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

# Repository names are lower case, and a tag may not contain a slash
docker build -t myapp:1.0 .     # not MyApp:1.0

# An unset variable breaks the reference silently
echo "[$REGISTRY]"              # prints [] when unset
docker push "${REGISTRY:?set the registry first}/app:1.0"

# Quote volume paths, especially on macOS and Windows
docker run -v "$(pwd)/my data:/data" alpine ls /data

# Whitespace from a CI variable is a common and invisible cause
docker run "$(printf %s "$IMAGE" | tr -d '[:space:]')"

# Print the command before running it when it is built up dynamically
set -x

How to diagnose Docker errors

Docker errors are usually about the daemon (not running, or not reachable by your user), the host (disk full, port already bound), or the image (wrong architecture, rate-limited pull, missing credentials). Apple Silicon and ARM cloud instances made architecture mismatches far more common. exec format error is the signature, and it means an amd64 binary is being run on arm64 or vice versa.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. Check the daemon before anything else: docker info. A "cannot connect to the Docker daemon" error is a socket permission or service problem, never an image problem.
2. Reclaim space deliberately with docker system df to see where it went, then docker system prune. Build cache and dangling volumes are usually the bulk of it.
3. For exec format error, run docker image inspect --format '{{.Architecture}}' image:tag and compare with uname -m. Build multi-arch images with docker buildx build --platform linux/amd64,linux/arm64.
4. Find what is holding a port with ss -tulpn | grep :PORT (or lsof -i :PORT) rather than restarting Docker and hoping.
5. Read build failures from the first error, not the last. BuildKit prints failing steps out of order, and the final line is often a downstream consequence.

Tools worth reaching for

• docker info
• docker system df
• docker buildx
• ss -tulpn
• docker logs --tail 100

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 docs.docker.com

Related Docker errors

• Docker build: failed to compute cache key, not foundA COPY or ADD source does not exist in the build context. The context is the directory sent…
• Docker build: layer caching issuesDocker build failing or not using cache properly, resulting in slow builds or unexpected…
• docker buildx: no builder instance foundbuildx needs a builder backed by BuildKit. On a fresh install, in CI, or after docker context…
• Docker Compose: dependency failed to start: container is unhealthyA service waited on another with condition service_healthy and that container's healthcheck…
• Docker Compose: network configuration errorDocker Compose cannot create or connect to network. Name conflict, subnet overlap, or network…
• docker push: unauthorized: authentication requiredThe registry refused the push. Either you are not logged in to that registry host, the token…
• Docker registry: 429 too many requestsRegistry (e.g., Docker Hub) rate limits unauthenticated or high-volume pulls.
• docker-compose: command not foundCompose V1, the standalone Python binary invoked as docker-compose, reached end of life and…

See all 27 Docker errors →

Browse other categories

• HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.
• Frontend 23Hydration mismatches, bundler resolution, layout shift and font loading.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.