What causes "default context cannot be created nor updated" in docker/cli?

Choose a non-reserved name for the context you want to persist

docker/cli · error · invalidParameterErr

default context cannot be created nor updated

Error message

default context cannot be created nor updated

What it means

ContextStoreWithDefault.CreateOrUpdate() guards the reserved name "default": because the default context is resolved on the fly from env/config rather than persisted, the store rejects any attempt to write metadata under that name, returning an invalidParameter error.

Solutions

Choose a non-reserved name for the context you want to persist
To alter the default's connection, set DOCKER_HOST / TLS env vars instead
Filter out "default" before bulk-writing contexts

Example fix

// before
store.CreateOrUpdate(store.Metadata{Name: "default", ...})
// after
store.CreateOrUpdate(store.Metadata{Name: "myctx", ...})

Defensive patterns

Strategy: validation

Validate before calling

if meta.Name == command.DefaultContextName {
    return fmt.Errorf("cannot create or update the reserved %q context; use env vars to configure it", command.DefaultContextName)
}
return store.CreateOrUpdate(meta)

Type guard

func isReservedContextName(name string) bool { return name == command.DefaultContextName }

Prevention

Never reuse "default" as a custom context name
Filter reserved names before bulk-writing contexts programmatically
Configure the default context via DOCKER_HOST and DOCKER_* TLS env vars

When it happens

Trigger: Programmatically calling store.CreateOrUpdate(store.Metadata{Name: "default", ...}) on a ContextStoreWithDefault, or `docker context create default` which routes here.

Common situations: Migration tooling that round-trips all contexts through CreateOrUpdate; scripts that reuse "default" as a custom name expecting to override it.

Related errors

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/d1c836994f04d2e6. Report an issue: GitHub.

Appendix: 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 4f84911bfe)