docker/cli · error

context metadata is not a valid DockerContext

Error message

context metadata is not a valid DockerContext

What it means

GetDockerContext converts the untyped store.Metadata.Metadata field into the typed DockerContext struct via a Go type assertion. The store deserializes metadata using a config function registered by the CLI; if the stored value is present but is not a DockerContext (assertion `storeMetadata.Metadata.(DockerContext)` fails), this error is returned. It signals corrupted or foreign-format context metadata rather than a missing one (nil metadata is treated as valid and returns a zero value).

Source

Thrown at cli/command/context.go:61

			if dc.AdditionalFields == nil {
				dc.AdditionalFields = make(map[string]any)
			}
			dc.AdditionalFields[k] = v
		}
	}
	return nil
}

// GetDockerContext extracts metadata from stored context metadata
func GetDockerContext(storeMetadata store.Metadata) (DockerContext, error) {
	if storeMetadata.Metadata == nil {
		// can happen if we save endpoints before assigning a context metadata
		// it is totally valid, and we should return a default initialized value
		return DockerContext{}, nil
	}
	res, ok := storeMetadata.Metadata.(DockerContext)
	if !ok {
		return DockerContext{}, errors.New("context metadata is not a valid DockerContext")
	}
	if storeMetadata.Name == DefaultContextName {
		res.Description = "Current DOCKER_HOST based configuration"
	}
	return res, nil
}

View on GitHub (pinned to e9452d6e78)

Solutions

1. Recreate the affected context: `docker context rm <name>` (or delete its directory under ~/.docker/contexts/meta/) then `docker context create <name> --docker host=...`.
2. If embedding docker/cli, build the store with command.DefaultContextStoreConfig() so metadata unmarshals into command.DockerContext.
3. Inspect ~/.docker/contexts/meta/*/meta.json for hand-edits or corruption and restore valid JSON.

Example fix

// before (library use)
st := store.New(dir, store.NewConfig(func() any { return &map[string]any{} }))
// after
st := store.New(dir, command.DefaultContextStoreConfig())

When it happens

Trigger: Calling command.GetDockerContext on a store.Metadata whose Metadata field holds a different concrete type — e.g. a context store read without the CLI's metadata type registration, metadata written by third-party tooling embedding docker/cli with a different config, or a hand-edited/corrupted meta.json under ~/.docker/contexts/meta/<sha>/ that unmarshals into an unexpected type.

Common situations: Programs importing docker/cli as a library and constructing a context store with their own store.NewConfig registration then passing results to CLI helpers; corrupted context files after disk issues or manual edits; mixing incompatible docker/cli versions that changed metadata typing.

Related errors

• plugin SchemaVersion version cannot be empty
• conflicting options: cannot specify both --host and --contex
• docker endpoint configuration is required
• cannot use --docker flag when --from is set
• cowardly refusing to export to a terminal, specify a file pa

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