How to fix Error: default context cannot be removed in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 155 views

The 'default context cannot be removed' error occurs when attempting to delete Docker's built-in default context using 'docker context rm default'. This is expected behavior since the default context is a reserved, protected context that Docker requires for baseline operations.

Quick fix

Fixes Error: default context cannot be removed

# This will always fail - it's by design
docker context rm default
# Error: default context cannot be removed
  1. Understand why default cannot be removed
  2. Switch to a different context instead
  3. Create a new context for remote Docker hosts
  4. Remove other (non-default) contexts
docker — error
# This will always fail - it's by design
docker context rm default
# Error: default context cannot be removed
Error: default context cannot be removed

What this error means

The "default context cannot be removed" error indicates that you're attempting to delete Docker's built-in default context, which is a reserved context name protected by Docker's design. Docker contexts allow you to manage multiple Docker daemon connections from a single CLI installation. The "default" context is special - it represents the local Docker daemon connection via the Unix socket (`/var/run/docker.sock` on Linux/Mac or the named pipe on Windows). This context is automatically created and maintained by Docker and serves as the fallback connection when no other context is specified. Since the default context is essential infrastructure for the Docker CLI, Docker explicitly prevents its removal to ensure you always have a working baseline configuration. This protection exists to prevent users from accidentally leaving their Docker CLI in an unusable state.

Typical symptoms

  • Running 'docker context rm default' returns: Error: default context cannot be removed
  • Process 'docker context rm default' exited with code 1
  • VS Code Docker extension shows error when attempting to remove default context
  • Automation scripts fail when trying to clean up all Docker contexts
  • Unable to reset Docker contexts by removing and recreating default
  • CI/CD pipeline cleanup step fails when attempting to remove default context

Common causes

  1. Attempting to remove the default context which is reserved and protected by design
  2. Misunderstanding that 'default' is a special context name that cannot be modified or deleted
  3. Trying to reset Docker configuration by removing all contexts including default
  4. Automation scripts attempting to remove all contexts without excluding default
  5. Confusing the default context with a custom context named 'default' (not allowed)
  6. Attempting to force Docker to use only a remote context by removing local default

How to fix "Error: default context cannot be removed"

1Understand why default cannot be removed

The default context is Docker's built-in context that connects to your local Docker daemon. It cannot be removed because:

- It's a reserved context name with special protections
- Docker requires a baseline context for operations
- It ensures you always have a working local Docker connection

bash
# This will always fail - it's by design
docker context rm default
# Error: default context cannot be removed

Instead of trying to remove it, you should work with Docker contexts differently depending on your goal.

2Switch to a different context instead

If your goal is to stop using the default context and use a different one, simply switch contexts:

bash
# List available contexts
docker context ls

# Switch to a different context
docker context use my-remote-context

# Verify the switch (asterisk shows active context)
docker context ls

You can also temporarily override the context for a single command:

bash
# Use a specific context for one command
docker --context my-remote-context ps

# Or set an environment variable
export DOCKER_CONTEXT=my-remote-context
docker ps
3Create a new context for remote Docker hosts

If you want to work with a remote Docker daemon instead of the local one, create a new context:

bash
# Create context for SSH connection
docker context create remote-server --docker "host=ssh://user@192.168.1.100"

# Create context for TCP connection (with TLS)
docker context create remote-tcp \
  --docker "host=tcp://192.168.1.100:2376,ca=/certs/ca.pem,cert=/certs/cert.pem,key=/certs/key.pem"

# Create context for cloud providers
docker context create my-cloud --docker "host=tcp://cloud-endpoint:2376"

Then switch to your new context:

bash
docker context use remote-server
4Remove other (non-default) contexts

You can remove any context except default. To clean up contexts you no longer need:

bash
# Remove a single context
docker context rm my-old-context

# Force remove the currently active context (switches to default first)
docker context rm --force my-current-context

# Remove multiple contexts at once
docker context rm context1 context2 context3

To remove all non-default contexts:

bash
# List all context names except default, then remove them
docker context ls --format '{{.Name}}' | grep -v '^default$' | xargs -r docker context rm
5Reset to default context if stuck

If you've switched to a context that's no longer working and want to return to the default:

bash
# Switch back to default context
docker context use default

# If DOCKER_CONTEXT env var is set, unset it
unset DOCKER_CONTEXT
unset DOCKER_HOST

# Verify you're using default
docker context ls

If docker context use default fails, edit the config file:

bash
# View config
cat ~/.docker/config.json

# Remove or fix the currentContext entry
# Change "currentContext": "broken-context" to "currentContext": "default"
# Or remove the currentContext line entirely
6Update automation scripts to skip default

If you have scripts that clean up Docker contexts, modify them to exclude the default context:

bash
#!/bin/bash
# Clean up all contexts except default

for ctx in $(docker context ls --format '{{.Name}}'); do
  if [ "$ctx" != "default" ]; then
    echo "Removing context: $ctx"
    docker context rm "$ctx"
  fi
done

For CI/CD pipelines, always check before removing:

yaml
# GitHub Actions example
- name: Cleanup Docker contexts
  run: |
    docker context ls --format '{{.Name}}' | \
      grep -v '^default$' | \
      xargs -r docker context rm || true

Advanced notes

Why This Protection Exists: The default context represents the baseline Docker CLI configuration. Without it, Docker commands would have no default endpoint to connect to, potentially leaving users unable to run any Docker commands. This protection is intentional and cannot be bypassed.

The "default" context is special: Unlike custom contexts that you create (which are stored in ~/.docker/contexts/), the default context is essentially a "virtual" context representing the standard local Docker socket connection. It doesn't have a physical directory in the contexts folder.

Cannot Create a Context Named "default": Docker also prevents you from creating a custom context named "default":

bash
docker context create default --docker "host=tcp://remote:2376"
# Error: "default" is a reserved context name

Docker Desktop Considerations: When using Docker Desktop, you may see additional contexts like desktop-linux or desktop-windows. These are created by Docker Desktop and can be removed, but the core default context remains protected.

Alternative to Removing: If you want Docker to always use a non-default endpoint, instead of trying to remove default, set the DOCKER_HOST environment variable in your shell profile:

bash
# In ~/.bashrc or ~/.zshrc
export DOCKER_HOST=ssh://user@remote-server

This overrides the default context's endpoint without removing it.

Kubernetes/Minikube Users: Tools like Minikube create their own Docker contexts. After running minikube start, you can switch between Minikube's context and default:

bash
# Use Minikube's Docker daemon
eval $(minikube docker-env)

# Return to local Docker
eval $(minikube docker-env --unset)
docker context use default

Frequently asked questions

What does "Error: default context cannot be removed" mean?
The "default context cannot be removed" error indicates that you're attempting to delete Docker's built-in default context, which is a reserved context name protected by Docker's design. Docker contexts allow you to manage multiple Docker daemon connections from a single CLI installation. sock on Linux/Mac or the named pipe on Windows).
How do I fix "Error: default context cannot be removed"?
The 'default context cannot be removed' error occurs when attempting to delete Docker's built-in default context using 'docker context rm default'. This is expected behavior since the default context is a reserved, protected context that Docker requires for baseline operations.
What causes "Error: default context cannot be removed"?
Attempting to remove the default context which is reserved and protected by design Misunderstanding that 'default' is a special context name that cannot be modified or deleted Trying to reset Docker configuration by removing all contexts including default
Is the "Error: default context cannot be removed" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading