docker/compose · error · ErrNotImplemented

not implemented

Error message

not implemented

What it means

api.ErrNotImplemented signals that the active backend does not implement the requested action. A concrete in-repo example is cmd/compose/ps.go parseFilter: --filter source=... returns api.ErrNotImplemented because source filtering is defined but not yet built. It lets the api surface declare capability gaps explicitly.

Source

Thrown at pkg/api/errors.go:39

)

const (
	// ExitCodeLoginRequired exit code when command cannot execute because it requires cloud login
	// This will be used by VSCode to detect when creating context if the user needs to login first
	ExitCodeLoginRequired = 5
)

var (
	// ErrNotFound is returned when an object is not found
	ErrNotFound = errors.New("not found")
	// ErrAlreadyExists is returned when an object already exists
	ErrAlreadyExists = errors.New("already exists")
	// ErrForbidden is returned when an operation is not permitted
	ErrForbidden = errors.New("forbidden")
	// ErrUnknown is returned when the error type is unmapped
	ErrUnknown = errors.New("unknown")
	// ErrNotImplemented is returned when a backend doesn't implement an action
	ErrNotImplemented = errors.New("not implemented")
	// ErrUnsupportedFlag is returned when a backend doesn't support a flag
	ErrUnsupportedFlag = errors.New("unsupported flag")
	// ErrCanceled is returned when the command was canceled by user
	ErrCanceled = errors.New("canceled")
	// ErrParsingFailed is returned when a string cannot be parsed
	ErrParsingFailed = errors.New("parsing failed")
	// ErrNoResources is returned when operation didn't selected any resource
	ErrNoResources = errors.New("no resources")
)

// IsNotFoundError returns true if the unwrapped error is ErrNotFound
func IsNotFoundError(err error) bool {
	return errors.Is(err, ErrNotFound)
}

// IsAlreadyExistsError returns true if the unwrapped error is ErrAlreadyExists
func IsAlreadyExistsError(err error) bool {
	return errors.Is(err, ErrAlreadyExists)

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Avoid the unsupported operation: for ps, filter with status=... or post-process JSON output instead of source=.
2. Check the current compose release notes — the capability may exist in a newer version, so upgrade.
3. In Go code, branch on api.IsErrNotImplemented (errors.Is) to degrade gracefully.

Example fix

# before
docker compose ps --filter source=local

# after
docker compose ps --format json | jq '.[] | select(.Publishers[0].Name == "local" or true)'

func isNotImplemented(err error) bool { return api.IsErrNotImplemented(err) }

if err := psOpts.parseFilter(); err != nil {
    if api.IsErrNotImplemented(err) {
        // feature reserved but absent: skip or use JSON filtering instead
    }
    return err
}

When it happens

Trigger: Running `docker compose ps --filter source=...`; or programmatically invoking an api method that the selected backend (e.g. compose vs cloud) has not implemented, which returns this sentinel.

Common situations: Using flags documented for other docker commands that compose has reserved but not implemented yet; switching a workflow to a backend with a smaller feature set and hitting unimplemented endpoints.

Related errors

• not found
• already exists
• forbidden
• unknown
• unsupported flag

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/038476637e6042e1. Report an issue: GitHub.