{"record":{"id":"f06145e328b3d64e","repo":"docker/compose","slug":"unknown","errorCode":null,"errorMessage":"unknown","messagePattern":"unknown","errorType":"error_code","errorClass":"ErrUnknown","httpStatus":null,"severity":"error","filePath":"pkg/api/errors.go","lineNumber":37,"sourceCode":"import (\n\t\"errors\"\n)\n\nconst (\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","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/api/errors.go#L19-L55","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the full error chain (err and wrapped causes) rather than relying on the sentinel.","Update docker compose and the engine to reduce version-skew mapping gaps.","Reproduce with verbose logging (COMPOSE_TRACE / --verbose, debug daemon logs) to expose the original backend error."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"func isUnknown(err error) bool { return errors.Is(err, api.ErrUnknown) }","tryCatchPattern":"if err := op(ctx); err != nil && errors.Is(err, api.ErrUnknown) {\n    log.Printf(\"unmapped backend error, inspect chain: %+v\", err)\n    // fall back to error-chain introspection, not the sentinel\n}","preventionTips":["Log full error chains (%+v / errors.Unwrap) when diagnosing unmapped errors.","Keep compose CLI and engine versions aligned to shrink unmapped surface."],"tags":["api","sentinel-error","unknown"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}