{"record":{"id":"caf3bbbd14e7a464","repo":"docker/compose","slug":"unsupported-flag","errorCode":null,"errorMessage":"unsupported flag","messagePattern":"unsupported flag","errorType":"error_code","errorClass":"ErrUnsupportedFlag","httpStatus":null,"severity":"error","filePath":"pkg/api/errors.go","lineNumber":41,"sourceCode":"const (\n\t// ExitCodeLoginRequired exit code when command cannot execute because it requires cloud login\n\t// This will be used by VSCode to detect when creating context if the user needs to login first\n\tExitCodeLoginRequired = 5\n)\n\nvar (\n\t// ErrNotFound is returned when an object is not found\n\tErrNotFound = errors.New(\"not found\")\n\t// ErrAlreadyExists is returned when an object already exists\n\tErrAlreadyExists = errors.New(\"already exists\")\n\t// ErrForbidden is returned when an operation is not permitted\n\tErrForbidden = errors.New(\"forbidden\")\n\t// ErrUnknown is returned when the error type is unmapped\n\tErrUnknown = errors.New(\"unknown\")\n\t// ErrNotImplemented is returned when a backend doesn't implement an action\n\tErrNotImplemented = errors.New(\"not implemented\")\n\t// ErrUnsupportedFlag is returned when a backend doesn't support a flag\n\tErrUnsupportedFlag = errors.New(\"unsupported flag\")\n\t// ErrCanceled is returned when the command was canceled by user\n\tErrCanceled = errors.New(\"canceled\")\n\t// ErrParsingFailed is returned when a string cannot be parsed\n\tErrParsingFailed = errors.New(\"parsing failed\")\n\t// ErrNoResources is returned when operation didn't selected any resource\n\tErrNoResources = errors.New(\"no resources\")\n)\n\n// IsNotFoundError returns true if the unwrapped error is ErrNotFound\nfunc IsNotFoundError(err error) bool {\n\treturn errors.Is(err, ErrNotFound)\n}\n\n// IsAlreadyExistsError returns true if the unwrapped error is ErrAlreadyExists\nfunc IsAlreadyExistsError(err error) bool {\n\treturn errors.Is(err, ErrAlreadyExists)\n}\n","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/api/errors.go#L23-L59","documentation":"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.","triggerScenarios":"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.","commonSituations":"Mixed environments where a script works locally but fails through a cloud context; version differences where a newer flag meets an older backend.","solutions":["Remove the unsupported flag from the invocation or gate it per backend.","Update the backend/CLI so both sides support the flag.","Detect programmatically with api.IsErrUnsupportedFlag and retry without the optional flag when it is not essential."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"func isUnsupportedFlag(err error) bool { return api.IsErrUnsupportedFlag(err) }","tryCatchPattern":"err := runWithFlag(ctx, flag)\nif err != nil && api.IsErrUnsupportedFlag(err) {\n    err = runWithoutFlag(ctx) // drop optional flag and retry once\n}","preventionTips":["Gate optional flags per backend in wrappers so unsupported combinations never reach the backend.","Update both CLI and backend together to keep flag support in sync."],"tags":["api","sentinel-error","flags","backend"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}