docker/cli · error

failed to remove context

Error message

failed to remove context %s: %w

What it means

Returned by ContextStore.Remove when removing the context's metadata fails; wraps the meta.remove error (which itself is 508). This is the first of two removal steps — if it fails, TLS removal (511) is not attempted.

Solutions

1. Fix ownership/permissions on ~/.docker/contexts/meta/<hash>.
2. Remove the metadata directory manually as the appropriate user.
3. Verify the filesystem is writable.

if err := store.Remove(name); err != nil {
    if errors.Is(err, os.ErrPermission) {
        // chown the meta dir, or rm -rf ~/.docker/contexts/meta/<hash> as the owner
    }
    return err
}

When it happens

Trigger: Calling store.Remove(name) when the metadata directory cannot be deleted (permissions, read-only FS, locked files).

Common situations: Ownership mismatch between files and the running user; read-only filesystem; files locked by another process.

Related errors

• failed to remove metadata
• failed to remove the CID file
• failed to read TLS data for endpoint
• failed to remove TLS data
• failed to remove TLS data for endpoint

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

Appendix: source

Thrown at cli/context/store/store.go:144

	if err != nil {
		return nil, err
	}
	names := make([]string, 0, len(list))
	for _, item := range list {
		names = append(names, item.Name)
	}
	return names, nil
}

// CreateOrUpdate creates or updates metadata for the context.
func (s *ContextStore) CreateOrUpdate(meta Metadata) error {
	return s.meta.createOrUpdate(meta)
}

// Remove deletes the context with the given name, if found.
func (s *ContextStore) Remove(name string) error {
	if err := s.meta.remove(name); err != nil {
		return fmt.Errorf("failed to remove context %s: %w", name, err)
	}
	if err := s.tls.remove(name); err != nil {
		return fmt.Errorf("failed to remove context %s: %w", name, err)
	}
	return nil
}

// GetMetadata returns the metadata for the context with the given name.
// It returns an errdefs.ErrNotFound if the context was not found.
func (s *ContextStore) GetMetadata(name string) (Metadata, error) {
	return s.meta.get(name)
}

// ResetTLSMaterial removes TLS data for all endpoints in the context and replaces
// it with the new data.
func (s *ContextStore) ResetTLSMaterial(name string, data *ContextTLSData) error {
	if err := s.tls.remove(name); err != nil {
		return err

View on GitHub (pinned to 4f84911bfe)