docker/cli · error

context metadata is not a valid DockerContext

Error message

context metadata is not a valid DockerContext

What it means

Returned by GetDockerContext when the stored context's Metadata field is non-nil but cannot be type-asserted to DockerContext (the store.Metadata.Metadata is `any`). This means the on-disk context metadata was written by a different/newer schema or corrupted, so its concrete type is not the expected DockerContext struct at context.go:59-61.

Solutions

1. Recreate the context: `docker context rm <name>` then `docker context create <name> --docker host=...`.
2. Inspect ~/.docker/contexts/meta/<id>/meta.json and fix or remove the malformed entry.
3. If caused by a version change, re-export and re-import the context with the current CLI version.
4. Fall back to the default context (`docker context use default`) to confirm the store works.

Example fix

// before
# meta.json has Metadata as a raw map, not a DockerContext
docker context use broken

// after
docker context rm broken
docker context create broken --docker host=unix:///var/run/docker.sock
docker context use broken

func isDockerContext(m store.Metadata) bool {
    if m.Metadata == nil {
        return true // valid default
    }
    _, ok := m.Metadata.(command.DockerContext)
    return ok
}

if !isDockerContext(meta) {
    return fmt.Errorf("context metadata is not a valid DockerContext: %s", meta.Name)
}

func AsDockerContext(m store.Metadata) (command.DockerContext, bool) {
    if m.Metadata == nil {
        return command.DockerContext{}, true
    }
    dc, ok := m.Metadata.(command.DockerContext)
    return dc, ok
}

dc, err := command.GetDockerContext(meta)
if err != nil {
    // metadata shape mismatch — recreate the context
    log.Printf("context %s metadata invalid, recreating", meta.Name)
    _ = contextStore.Remove(meta.Name)
    return recreateContext(meta.Name)
}

When it happens

Trigger: Calling GetDockerContext on a context whose metadata was stored as a raw map[string]interface{} or a different struct (e.g. a kubernetes/aci context endpoint overwriting the docker metadata). Happens after manual edits of ~/.docker/contexts/meta/*/meta.json or cross-tool context sharing.

Common situations: Downgrading/upgrading the CLI across versions that changed the metadata schema. Manually editing context meta.json files. Plugins (aci/ecs) writing metadata in incompatible shapes. Context store corruption.

Related errors

• cannot find docker endpoint in context
• invalid context: no metadata found
• error while getting existing contexts
• endpoint is not of type EndpointMeta
• parsing

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

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