🐳 Docker Error Guide: 'context not found' from docker context use

Exact Error Message

$ docker context use production
context not found: context "production" does not exist

The same failure appears when you target a context per-command or through the environment:

$ docker --context production ps
context "production": context not found: open /home/user/.docker/contexts/meta/<hash>/meta.json: no such file or directory

Both are the same problem: Docker cannot resolve the named context to a stored endpoint definition.

What It Means

A Docker context is a named bundle of connection settings — the daemon endpoint (a local socket, an ssh:// host, or a TCP address) plus any TLS material — stored under ~/.docker/contexts/. docker context use sets the active context, and --context selects one for a single command. When you reference a name that has no matching directory on disk, Docker reports context not found and refuses to switch.

This is a client-side lookup failure. The remote daemon may be perfectly healthy; Docker simply has no local record of a context by that name, usually because it was never created, was created for a different user, or its metadata was deleted.

Common Causes

• The context name is misspelled or differs in case from the stored one.
• The context was never created on this machine (created on another host or in CI).
• The context lives in a different user’s home; you created it as your user but are now running under sudo or a service account.
• $DOCKER_CONFIG or $HOME points somewhere other than where the context was stored.
• The ~/.docker/contexts/meta directory was deleted, wiped by a cleanup script, or lost in a home-directory restore.
• A tool or script referenced $DOCKER_CONTEXT with a stale value.

Diagnostic Commands

List every context Docker can actually see and which is active:

docker context ls

Inspect the exact name and endpoint of a context (this confirms the stored spelling):

docker context inspect production

Check which config directory Docker is reading from — a wrong DOCKER_CONFIG/HOME is a common culprit:

echo "DOCKER_CONFIG=$DOCKER_CONFIG HOME=$HOME DOCKER_CONTEXT=$DOCKER_CONTEXT"
ls -la "${DOCKER_CONFIG:-$HOME/.docker}/contexts/meta"

Reproduce under the exact identity that fails (for example under sudo):

sudo docker context ls

Step-by-Step Resolution

1. List the real context names and compare against what you typed. The name in docker context ls is authoritative — match its case exactly:

docker context ls

2. If the context genuinely does not exist, create it with the correct endpoint. For an SSH-reachable daemon:

docker context create production \
  --docker "host=ssh://deploy@prod-host.example.com" \
  --description "Production swarm manager"

For a TCP endpoint with TLS:

docker context create production \
  --docker "host=tcp://10.0.0.5:2376,ca=~/certs/ca.pem,cert=~/certs/cert.pem,key=~/certs/key.pem"

3. Activate it and confirm the switch:

docker context use production
docker context ls

4. If the context exists for your user but fails under sudo, either run without sudo or point the elevated command at your config directory instead of recreating it:

sudo DOCKER_CONFIG="$HOME/.docker" docker --context production ps

5. If a script set a stale DOCKER_CONTEXT, unset it so it stops overriding your selection:

unset DOCKER_CONTEXT

6. Verify connectivity through the restored context:

docker --context production version

A populated Server: block confirms the client reached the intended daemon.

Prevention

• Treat context definitions as portable config: recreate them with a small idempotent script on each new machine rather than assuming they follow you.
• Export and import contexts across hosts with docker context export production / docker context import, so CI and workstations stay in sync.
• Be deliberate about sudo; contexts are per-user, so a context created as your user is invisible to root unless you pass DOCKER_CONFIG.
• Avoid hard-coding DOCKER_CONTEXT in shared shell profiles where a stale value silently overrides docker context use.
• Back up ~/.docker/contexts alongside other dotfiles so a home restore does not silently drop your endpoints.

Related Errors

• Cannot connect to the Docker daemon at unix:///var/run/docker.sock — the context resolved but the endpoint is unreachable; a connectivity issue, not a missing context.
• error during connect: ... ssh: connect to host ... port 22: Connection refused — the SSH endpoint of a valid context is down.
• context "default" cannot be removed — the built-in default context is protected; unrelated to a missing custom one.
• DOCKER_HOST and DOCKER_CONTEXT are mutually exclusive — a conflicting-selection error rather than a lookup failure.

Frequently Asked Questions

Where does Docker store contexts? Under ~/.docker/contexts/meta/ (or $DOCKER_CONFIG/contexts/meta when that variable is set). Each context is a hashed subdirectory containing a meta.json endpoint definition.

Why does the context work as my user but not under sudo? Contexts are keyed to the invoking user’s home directory. Under sudo, $HOME changes and Docker looks in root’s config. Pass DOCKER_CONFIG="$HOME/.docker" or run without sudo.

How do I move a context to another machine? Use docker context export production to write a .tar, copy it over, and run docker context import production production.dockercontext on the target. You can script this with a template from the DevOps AI prompt library at /prompts/?stack=docker.

Can an environment variable override docker context use? Yes. DOCKER_CONTEXT takes precedence over the persisted active context, and DOCKER_HOST overrides both. A stale value in a shell profile is a frequent cause of surprise.

Is deleting ~/.docker/contexts safe? It only removes your custom contexts; the built-in default context is always regenerated. You will need to recreate any named contexts afterward. For more daemon-connection fixes, see the Docker guides.