What causes "context not found: %w" in docker/cli?

Create the context (`docker context create ...`) or switch to 'default' (`docker context use default`).

context not found

Error message

context not found: %w

What it means

Returned as an errdefs NotFound error by GetMetadata/getByID when the context's meta.json does not exist on disk. The notFound() wrapper makes it satisfy errdefs.IsNotFound, so callers can distinguish 'missing' from 'broken'.

Solutions

Create the context (`docker context create <name> ...`) or switch to 'default' (`docker context use default`).
Verify spelling against `docker context ls`.
Confirm DOCKER_CONFIG / the store root points at the directory holding your contexts.

Defensive patterns

Strategy: validation

Validate before calling

// Check existence without erroring before GetMetadata.
func contextExists(s store.ReaderLister, name string) (bool, error) {
    list, err := s.List()
    if err != nil {
        return false, err
    }
    for _, m := range list {
        if m.Name == name {
            return true, nil
        }
    }
    return false, nil
}

Try / catch

if _, err := store.GetMetadata(name); err != nil {
    if errors.Is(err, errdefs.ErrNotFound) {
        // context is absent — handle gracefully
    }
}

Prevention

Confirm DOCKER_CONFIG points at the directory holding your contexts.
Use `docker context ls` to verify exact names before scripting against them.
Default to 'default' when an arbitrary name may not exist.

When it happens

Trigger: Calling store.GetMetadata(name) for a name with no directory under the store's meta root: the context was never created, was deleted, or the store root points at the wrong location (e.g. wrong DOCKER_CONFIG).

Common situations: Fresh install with only 'default'; typo in name; stale DOCKER_CONTEXT env var; DOCKER_CONFIG pointing at a different config directory; referencing a context removed on another machine via a synced home dir.

Related errors

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

Appendix: source

Thrown at cli/context/store/metadatastore.go:76

		return nil, err
	}
	return reflect.ValueOf(typed).Elem().Interface(), nil
}

func (s *metadataStore) get(name string) (Metadata, error) {
	m, err := s.getByID(contextdirOf(name))
	if err != nil {
		return m, fmt.Errorf("context %q: %w", name, err)
	}
	return m, nil
}

func (s *metadataStore) getByID(id contextdir) (Metadata, error) {
	fileName := filepath.Join(s.contextDir(id), metaFile)
	bytes, err := os.ReadFile(fileName)
	if err != nil {
		if errors.Is(err, os.ErrNotExist) {
			return Metadata{}, notFound(fmt.Errorf("context not found: %w", err))
		}
		return Metadata{}, err
	}
	var untyped untypedContextMetadata
	r := Metadata{
		Endpoints: make(map[string]any),
	}
	if err := json.Unmarshal(bytes, &untyped); err != nil {
		return Metadata{}, fmt.Errorf("parsing %s: %v", fileName, err)
	}
	r.Name = untyped.Name
	if r.Metadata, err = parseTypedOrMap(untyped.Metadata, s.config.contextType); err != nil {
		return Metadata{}, fmt.Errorf("parsing %s: %v", fileName, err)
	}
	for k, v := range untyped.Endpoints {
		if r.Endpoints[k], err = parseTypedOrMap(v, s.config.endpointTypes[k]); err != nil {
			return Metadata{}, fmt.Errorf("parsing %s: %v", fileName, err)
		}

View on GitHub (pinned to 4f84911bfe)