docker/cli · error · invalidParameter

default context cannot be created nor updated

Error message

default context cannot be created nor updated

What it means

ContextStoreWithDefault wraps the on-disk context store and injects the virtual 'default' context, whose settings come from environment variables and CLI flags rather than stored files. Its CreateOrUpdate override rejects any write where meta.Name == 'default' with an invalid-parameter error, since there is no backing storage for the default context and writes to it would be silently meaningless.

Source

Thrown at cli/command/defaultcontextstore.go:121

}

// List implements store.Store's List
func (s *ContextStoreWithDefault) List() ([]store.Metadata, error) {
	contextList, err := s.Store.List()
	if err != nil {
		return nil, err
	}
	defaultContext, err := s.Resolver()
	if err != nil {
		return nil, err
	}
	return append(contextList, defaultContext.Meta), nil
}

// CreateOrUpdate is not allowed for the default context and fails
func (s *ContextStoreWithDefault) CreateOrUpdate(meta store.Metadata) error {
	if meta.Name == DefaultContextName {
		return invalidParameter(errors.New("default context cannot be created nor updated"))
	}
	return s.Store.CreateOrUpdate(meta)
}

// Remove is not allowed for the default context and fails
func (s *ContextStoreWithDefault) Remove(name string) error {
	if name == DefaultContextName {
		return invalidParameter(errors.New("default context cannot be removed"))
	}
	return s.Store.Remove(name)
}

// GetMetadata implements store.Store's GetMetadata
func (s *ContextStoreWithDefault) GetMetadata(name string) (store.Metadata, error) {
	if name == DefaultContextName {
		defaultContext, err := s.Resolver()
		if err != nil {
			return store.Metadata{}, err

View on GitHub (pinned to e9452d6e78)

Solutions

1. Create a differently-named context and switch to it: `docker context create mydefault --docker "host=..." && docker context use mydefault`.
2. To alter the default context's endpoint, set DOCKER_HOST (and DOCKER_TLS_VERIFY/DOCKER_CERT_PATH) in the environment instead of writing to the store.
3. When importing, pick another name: `docker context import restored ctx.tar`.

Example fix

# before
docker context update default --docker "host=ssh://user@host"
# after
docker context create remote --docker "host=ssh://user@host"
docker context use remote

When it happens

Trigger: Any code path calling ContextStoreWithDefault.CreateOrUpdate with Metadata.Name == "default" (cli/command/defaultcontextstore.go:119-121) — e.g. `docker context create default --docker ...`, `docker context update default ...`, `docker context import default file.tar`, or library code writing through the CLI's context store.

Common situations: Trying to change the default context's endpoint with `docker context update default` (the right lever is DOCKER_HOST or a new context); importing an exported context under the name 'default'; automation that regenerates contexts and includes the default in its write set.

Related errors

• context "default" cannot be removed
• conflicting options: cannot specify both --host and --contex
• context metadata is not a valid DockerContext
• docker endpoint configuration is required
• cannot use --docker flag when --from is set

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/d1c836994f04d2e6.json. Report an issue: GitHub.