## Intro Docker Contexts are a powerful feature for switching between Docker daemons, but when misconfigured they cause subtle errors that waste developer time. This guide provides a systematic approach to identify, diagnose, and recover from common Docker Context problems. By following the practical steps, you will understand your environment, verify configurations, and restore a working Docker setup. This article covers: - Inventorying your Docker version and context settings. - Safe configuration paths to avoid breaking changes. - Diagnostic commands with expected outputs. - Common failure modes and step-by-step recovery. - A repeatable operations checklist. Whether you are switching between local and remote Docker hosts, using Docker Desktop or a remote engine, this guide will help you resolve issues quickly and with confidence. ## Version and Environment Inventory Before making any changes, record the exact versions and current context configuration. This establishes a known state and aids in rollback. Start by checking the Docker CLI and daemon versions, listing all contexts, and inspecting the active context in detail. ### Checking Docker and CLI Versions Run the following command to see both client and server information: ```bash docker version ``` Expected output (abbreviated): ``` Client: Docker Engine - Community Version: 24.0.7 API version: 1.43 Go version: go1.20.10 Git commit: 311b9ff Built: Thu Oct 26 09:08:15 2023 OS/Arch: linux/amd64 Context: default Server: Docker Engine - Community Engine: Version: 24.0.7 API version: 1.43 (minimum version 1.12) Go version: go1.20.10 Git commit: 311b9ff Built: Thu Oct 26 09:07:41 2023 OS/Arch: linux/amd64 Experimental: false ``` Note the client and server versions; a mismatch can cause API compatibility issues. For example, a Docker CLI version 24.0.7 using API 1.43 cannot talk to a Docker daemon that only supports API 1.41. If the versions differ significantly, consider upgrading or downgrading one component. ### Listing Docker Contexts View all contexts and identify the active one (marked with an asterisk): ```bash docker context ls ``` Expected output: ``` NAME TYPE DESCRIPTION DOCKER ENDPOINT KUBERNETES ENDPOINT ORCHESTRATOR default moby Current DOCKER_HOST based config unix:///var/run/docker.sock swarm remote * moby Remote Docker host tcp://192.168.1.100:2375 ``` The asterisk indicates the active context. If the context you expect is not active, that is a common issue. For example, after a reboot or Docker Desktop update, the active context may revert to `default`. ### Inspecting a Specific Context For detailed configuration of a context, use: ```bash docker context inspect ``` Example: ```bash docker context inspect remote ``` Expected output: ```json [ { "Name": "remote", "Metadata": {}, "Endpoints": { "docker": { "Host": "tcp://192.168.1.100:2375", "SkipTLSVerify": false } }, "TLSMaterial": {}, "Storage": { "MetadataPath": "/home/user/.docker/contexts/meta/...", "TLSPath": "/home/user/.docker/contexts/tls/..." } } ] ``` Check the `Host` field for correctness. Common mistakes include using `http://` instead of `tcp://`, forgetting the port, or specifying an IP address that is no longer reachable. ### Environment Prerequisites Ensure the following before proceeding: - Docker CLI is installed and functional. - Network connectivity to the Docker daemon (for remote contexts). - Sufficient permissions to manage Docker contexts (usually user-level, stored in `~/.docker/contexts`). - For TLS-enabled contexts, valid client certificates. Document these details before making any changes. For example, you might save the output of `docker version` and `docker context ls` to a file: ```bash docker version > docker-version-before.txt docker context ls > docker-contexts-before.txt ``` ## Safe Configuration Path When modifying Docker contexts, prefer non-destructive operations and create backups to enable rollback. This section covers creating contexts, switching safely, backing up metadata, using environment variables for temporary overrides, and scoping changes. ### Creating a Context To add a new context without altering existing ones, use `docker context create`. The syntax is: ```bash docker context create --docker "host=" ``` Example: ```bash docker context create myremote --docker "host=tcp://192.168.1.100:2375" ``` Expected output: ``` myremote Successfully created docker context "myremote" ``` This command creates a new context named `myremote` that points to the TCP endpoint. Additional options like `--description`, `--docker "ca=...,cert=...,key=..."` can be used for TLS. ### Switching Contexts Safely Switch to a context temporarily for testing: ```bash docker context use myremote ``` Expected output: ``` myremote Current context is now "myremote" ``` After testing, switch back to the original context to avoid impacting other work. For example, if you were previously using `default`, run: ```bash docker context use default ``` Note that switching the context changes the Docker CLI's target for all subsequent commands in the current shell. It does not affect other shells or background processes. ### Backing Up Context Metadata The Docker context metadata is stored in `~/.docker/contexts`. Create a backup before deleting or modifying: ```bash cp -r ~/.docker/contexts ~/.docker/contexts-backup-$(date +%Y%m%d) ``` This preserves all context definitions, including TLS material. To restore later, copy the backup back: ```bash cp -r ~/.docker/contexts-backup-YYYYMMDD ~/.docker/contexts ``` ### Using Environment Variables as Overrides For temporary changes, set the `DOCKER_CONTEXT` environment variable: ```bash export DOCKER_CONTEXT=myremote docker ps ``` This overrides the active context for the current shell session only. It is useful for testing a context without changing the global default. To unset, use: ```bash unset DOCKER_CONTEXT ``` Alternatively, you can use the `--context` flag on individual commands, which takes precedence over the active context and `DOCKER_CONTEXT`: ```bash docker --context myremote ps ``` ### Scoping Changes - Avoid global modifications like `docker context rm` without a backup. - Prefer creating new contexts and switching rather than editing existing ones. - Test new contexts from a single shell before making them default. For example, if you need to update the endpoint of an existing context, consider creating a new context with the correct settings, test it, and then remove the old one only when you are confident. ## Verification and Diagnostics After configuring a context, verify it actually works by running basic Docker commands and checking connectivity. This section provides a sequence of diagnostics to confirm that the context is functional. ### Basic Connectivity Test Run `docker info` to confirm the daemon responds: ```bash docker info ``` Expected output (key fields): ``` Client: Context: myremote Debug Mode: false Server: Containers: 3 Running: 1 Paused: 0 Stopped: 2 Images: 10 Server Version: 24.0.7 Storage Driver: overlay2 ... ``` If the command hangs or times out, there may be a network issue or the daemon is not running. Use `docker info --format '{{.ServerVersion}}'` to quickly get the server version: ```bash docker info --format '{{.ServerVersion}}' ``` ### Testing with docker ps List containers on the active context: ```bash docker ps ``` Expected output (when no containers are running): ``` CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES ``` If the output is empty, the daemon is reachable but has no running containers. To see all containers (including stopped), use `docker ps -a`. ### Checking Logs Docker daemon logs can reveal connection problems. Look for lines containing `level=error` or `msg="..."` that indicate authentication failures, TLS issues, or network problems. - On Linux with systemd, use: ```bash journalctl -u docker.service -n 50 --no-pager ``` - On Docker Desktop, check the Dashboard logs or run `docker desktop logs` (if available). For example, a typical error in the logs might be: ``` level=error msg="Handler for GET /v1.43/containers/json returned error: error during connect: Get http://192.168.1.100:2375/v1.43/containers/json: dial tcp 192.168.1.100:2375: connect: connection refused" ``` ### Using docker context show Confirm which context is active: ```bash docker context show ``` Expected output: ``` myremote ``` If the output is `default` but you expected `myremote`, you need to switch contexts. ### Diagnosing TLS Issues If you encounter certificate errors, test the TLS connection directly with `curl`. For a Docker daemon secured with TLS on port 2376, run: ```bash curl https://192.168.1.100:2376/_ping --cacert ca.pem --cert cert.pem --key key.pem ``` Expected output: `OK` if TLS is correctly configured. If you get a certificate verification error, check the CA certificate path and ensure the client certificate is valid. For self-signed certificates, you may need to set `SkipTLSVerify` to `true` in the context (not recommended for production) or use the correct CA. ### Verifying Endpoint Resolution Ensure the hostname or IP address is reachable: ```bash ping 192.168.1.100 ``` Expected output: successful replies. If ping fails, check network connectivity and firewall rules. For TCP port checks, use `nc` (netcat): ```bash nc -zv 192.168.1.100 2375 ``` Expected output: `Connection to 192.168.1.100 2375 port [tcp/*] succeeded!` ## Failure Modes and Recovery This section describes common Docker Context failures and provides step-by-step recovery procedures. ### Failure: "Cannot connect to the Docker daemon" This error appears when the Docker CLI cannot reach the daemon at the configured endpoint. Common causes include: - Incorrect endpoint in the context. - The Docker daemon is not running. - Network connectivity issues or firewall blocking. - TLS misconfiguration. Recovery steps: 1. Check if the daemon is running: - On Linux: `systemctl status docker` - On Docker Desktop: verify the application is running. 2. Verify the endpoint: ```bash docker context inspect ``` Ensure the `Host` field is correct. For example, if it should be `tcp://192.168.1.100:2375`, look for typos. 3. Test network connectivity: ```bash nc -zv 192.168.1.100 2375 ``` Should show `open` or `succeeded`. 4. If using HTTPS, verify TLS settings as described earlier. 5. Check Docker daemon logs for more details. ### Failure: "Error response from daemon: client version 1.44 is too new" This indicates the Docker CLI is newer than the daemon and the API versions are incompatible. For example, CLI version 25.0.0 uses API 1.44, but the daemon only supports up to API 1.43. Recovery options: - Downgrade the Docker CLI to a version compatible with the daemon. - Upgrade the Docker daemon to a version that supports the newer API. - Temporarily set the `DOCKER_API_VERSION` environment variable to force a lower API version: ```bash export DOCKER_API_VERSION=1.43 docker ps ``` Note that this may not work if the CLI uses features not available in the older API. It is best to align versions properly. ### Failure: Context missing after update Sometimes after a Docker Desktop update or system upgrade, contexts may disappear. This can happen if the update process resets the `~/.docker/contexts` directory or if there is a migration issue. Recovery: - Restore from a backup if you have one: ```bash cp -r ~/.docker/contexts-backup-YYYYMMDD/* ~/.docker/contexts/ ``` - Recreate the context manually using `docker context create`. - Check if the context exists in another user profile or machine. ### Failure: TLS verification failed This occurs when the client certificates are expired, invalid, or the CA certificate is not trusted. Recovery: - Regenerate the client and server certificates using your CA. - Update the context with the new TLS material: ```bash docker context update --docker "host=tcp://192.168.1.100:2376,ca=/path/to/ca.pem,cert=/path/to/cert.pem,key=/path/to/key.pem" ``` - Test the TLS connection with `curl` as shown earlier. - If using self-signed certificates, consider setting `SkipTLSVerify=true` temporarily for testing (not secure for production). ### Rollback Procedure If a new context does not work, switch back to a known good context: ```bash docker context use default ``` If a context was deleted by mistake, restore from backup: ```bash cp -r ~/.docker/contexts-backup-YYYYMMDD/meta/* ~/.docker/contexts/meta/ cp -r ~/.docker/contexts-backup-YYYYMMDD/tls/* ~/.docker/contexts/tls/ ``` Then verify with `docker context ls`. ### Example Recovery Workflow Scenario: You created a context "badremote" with the wrong IP address `192.168.1.99` and switched to it. Now Docker commands fail with "Cannot connect to the Docker daemon". Step-by-step recovery: 1. Identify active context: ```bash docker context show ``` Output: `badremote` 2. Switch back to a known good context: ```bash docker context use default ``` Output: `Current context is now "default"` 3. Delete the faulty context: ```bash docker context rm badremote ``` Output: `badremote` (removed) 4. Recreate the context with the correct IP address: ```bash docker context create goodremote --docker "host=tcp://192.168.1.101:2375" ``` 5. Test the new context: ```bash docker context use goodremote docker info ``` If `docker info` returns server details, the context works. If not, repeat diagnostics. ## Operations Checklist Use the following checklist for routine Docker Context operations and troubleshooting. It summarizes the key commands and checks in a tabular format for quick reference. | Step | Action | Command / Check | |------|--------|-----------------| | 1 | List all contexts | `docker context ls` | | 2 | Show active context | `docker context show` | | 3 | Inspect context details | `docker context inspect ` | | 4 | Test daemon connectivity | `docker info` | | 5 | Verify container listing | `docker ps` | | 6 | Check Docker daemon logs | `journalctl -u docker.service -n 50 --no-pager` (Linux) | | 7 | Back up contexts before changes | `cp -r ~/.docker/contexts ~/.docker/contexts-backup-$(date +%Y%m%d)` | | 8 | Create new context | `docker context create --docker "host=..."` | | 9 | Switch context | `docker context use ` | | 10 | Remove unused context | `docker context rm ` | | 11 | Test TLS with curl | `curl /_ping --cacert ca.pem --cert cert.pem --key key.pem` | | 12 | Check port reachability | `nc -zv ` | Regularly review contexts and prune unused ones to avoid confusion. For example, run `docker context ls` monthly and remove contexts that are no longer needed. Also, document each context's purpose in the description field to make it easier to identify them later. ## Conclusion Docker Context troubleshooting becomes manageable with a systematic approach: inventory your environment, configure safely, verify with practical commands, and recover using known patterns. By following the steps in this guide, you can resolve most context issues without downtime. Key takeaways: - Always check `docker version` and `docker context ls` first. - Use non-destructive creation and switching, and back up context data. - Verify connectivity with `docker info` and `docker ps`. - Know how to roll back to a working context. - Maintain an operations checklist for consistency. Next steps: apply these techniques to your current Docker setup, document your specific contexts, and establish a backup routine. Consider automating context backups with a cron job or script to ensure you always have a recent copy.