docker/compose · error · ErrUnsupportedFlag

unsupported flag

Error message

unsupported flag

What it means

api.ErrUnsupportedFlag is returned when a command is invoked with a flag the active backend does not support. It exists so the CLI can give a precise 'this backend cannot honor this flag' signal instead of silently ignoring the option, and is detected via api.IsErrUnsupportedFlag / errors.Is.

Source

Thrown at pkg/api/errors.go:41

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. Remove the unsupported flag from the invocation or gate it per backend.
  2. Update the backend/CLI so both sides support the flag.
  3. Detect programmatically with api.IsErrUnsupportedFlag and retry without the optional flag when it is not essential.
Defensive patterns

Strategy: try-catch

Type guard

func isUnsupportedFlag(err error) bool { return api.IsErrUnsupportedFlag(err) }

Try / catch

err := runWithFlag(ctx, flag)
if err != nil && api.IsErrUnsupportedFlag(err) {
    err = runWithoutFlag(ctx) // drop optional flag and retry once
}

Prevention

When it happens

Trigger: Passing a flag valid for the local compose backend but unsupported by the cloud backend (or vice versa) for the same command; programmatic calls that forward arbitrary flags to a backend that rejects them.

Common situations: Mixed environments where a script works locally but fails through a cloud context; version differences where a newer flag meets an older backend.

Related errors

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