docker/compose · error · ErrUnknown

unknown

Error message

unknown

What it means

api.ErrUnknown is the fallback sentinel used when an error from a backend cannot be mapped to any specific category (not-found, forbidden, already-exists, etc.). Encountering it means the underlying failure is unmapped and its details are only available via the wrapped error chain or message, not the sentinel itself.

Source

Thrown at pkg/api/errors.go:37

import (
	"errors"
)

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

View on GitHub (pinned to ddc4b044b6)

Solutions

  1. Inspect the full error chain (err and wrapped causes) rather than relying on the sentinel.
  2. Update docker compose and the engine to reduce version-skew mapping gaps.
  3. Reproduce with verbose logging (COMPOSE_TRACE / --verbose, debug daemon logs) to expose the original backend error.
Defensive patterns

Strategy: try-catch

Type guard

func isUnknown(err error) bool { return errors.Is(err, api.ErrUnknown) }

Try / catch

if err := op(ctx); err != nil && errors.Is(err, api.ErrUnknown) {
    log.Printf("unmapped backend error, inspect chain: %+v", err)
    // fall back to error-chain introspection, not the sentinel
}

Prevention

When it happens

Trigger: A backend returning an error shape the mapper does not recognize; translation layers converting arbitrary engine errors into api-level errors and defaulting to ErrUnknown when no case matches.

Common situations: Newer engine features producing novel error types; version skew between compose CLI and backend; debugging sessions where the sentinel gives no signal and the root cause must be read from the wrapped error.

Related errors

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