Skip to content
🐋Cetacean

Error Reference

A domain-specific error carries a stable code as the last path segment of thetype field in itsRFC 9457 problem document —"type": "/api/errors/SVC001" is the entry below. Generic HTTP errors use about:blank and have no code.

A running Cetacean serves the same catalog at GET /api/errors, and one entry at GET /api/errors/{code}. This page is generated from the same source, so the two cannot disagree.

APIProtocol and content negotiation

API001SSE Not Supported406
This endpoint does not support Server-Sent Events.
HintUse Accept: application/json instead of text/event-stream.
API002SSE Required406
This endpoint only supports Server-Sent Events.
HintUse Accept: text/event-stream.
API003Not Acceptable406
The Accept header does not match any media type this endpoint can produce.
HintUse Accept: application/json, application/atom+xml, text/event-stream, or text/html.
API004Invalid Patch Content-Type415
The Content-Type header does not match a supported patch format.
HintUse Content-Type: application/merge-patch+json or application/json-patch+json.
API005Streaming Not Supported500
The server's response writer does not support streaming (no http.Flusher).
HintThis is a server configuration issue. Check that no middleware is buffering responses.
API006Invalid Request Body400
The request body could not be decoded as valid JSON.
HintEnsure the request body is well-formed JSON matching the expected schema.
API007Unreadable Request Body400
The request body could not be read.
HintEnsure the request includes a body and Content-Length is correct.
API008Invalid JSON400
The request body is not valid JSON.
HintCheck for syntax errors in the JSON payload.
API009Internal Serialization Error500
The server failed to serialize or deserialize internal state.
HintThis is a server bug. Check the Cetacean logs for details.
API010Patch Test Failed409
A JSON Patch test operation failed, indicating the resource state does not match the expected value.
HintReload the resource and retry the patch with updated test values.
API011Patch Application Failed400
The JSON Patch could not be applied to the resource.
HintCheck the patch operations for correctness.
API012Endpoint Removed410
This endpoint was deprecated and has since been removed.
HintSee the endpoint named in the detail, or GET /api for the current surface.
API013Precondition Failed412
The If-Match header did not match the current state of the resource.
HintRe-read the resource, take the ETag from that response, and retry with it.
API014Not Representable as Compose422
The resource has nothing a compose file can describe. A service running a plugin or a network attachment has no container specification, which is all a compose service is.
HintRead the resource as JSON instead; only container services have a compose projection.
API015Ambiguous Identifier409
The name in the path or request body identifies more than one resource, so the server cannot tell which one was meant. Swarm does not require node hostnames to be unique.
HintAddress the resource by its ID. The detail names every ID the request could have meant.

AUTAuthentication

AUT001Not Authenticated401
The request requires authentication but no valid credentials were provided.
HintLog in or provide a valid authentication token.
AUT002Authorization Denied403
The identity provider denied authorization.
HintCheck your account permissions with the identity provider.
AUT003Authentication Callback Error400
The authentication callback contained invalid or missing parameters.
HintRetry the login flow from the beginning.
AUT004Authentication Server Error500
An internal error occurred during authentication.
HintRetry the login flow. If the problem persists, check server logs.
AUT005Client Certificate Rejected403
The client certificate was absent, unreadable, or carried no usable identity.
HintPresent a certificate from a CA this deployment trusts, carrying a common name, email address or SPIFFE URI SAN.
AUT006Authentication Refused403
The credential this deployment authenticates with was missing or rejected, and no HTTP authentication scheme can ask for it.
HintThe credential comes from the network path — a trusted proxy's headers, or the peer's tailnet membership — not from the request. Check the server logs for which one failed.

ACLAuthorization

ACL001Access Denied403
You do not have permission to access this resource.
HintCheck your ACL policy grants.
ACL002Write Access Denied403
You do not have write permission on this resource.
HintCheck your ACL policy grants for write permissions.

OPSOperations level

OPS001Operations Level Too Low403
The requested operation requires a higher operations level than the server is configured for.
HintIncrease the server.operations_level setting and restart the server.

CSRCross-origin protection

CSR001Cross-Origin Request Blocked403
The request changes state and arrived from another origin, which cross-site request forgery protection refuses.
HintCall the API from an allowed origin, or add yours to the server.cors.origins setting.

FLTFilter expressions

FLT001Filter Expression Too Long400
The filter expression exceeds the maximum allowed length.
HintShorten the filter expression.
FLT002Invalid Filter Expression400
The filter expression could not be compiled, names a field the resource does not have, or compares values of different types.
HintCheck the expression syntax and the filter fields documented for this resource type. Filters use the expr-lang expression language.
FLT003Filter Evaluation Error400
The filter expression compiled but failed during evaluation.
HintCheck the values the expression passes to each operator and function.
FLT004Filter Too Expensive400
The filter expression was too expensive to evaluate over the list.
HintCompare fields of the resource instead of building large collections in the expression.

SEASearch

SEA001Missing Search Query400
The required query parameter q is missing.
HintProvide a search query: /search?q=term.
SEA002Search Query Too Long400
The search query exceeds the maximum allowed length of 200 characters.
HintShorten the search query.

MTRMetrics and Prometheus

MTR001Prometheus Not Configured503
Prometheus metrics are not available because no Prometheus URL is configured.
HintSet the prometheus.url setting and restart the server.
MTR002Prometheus Unreachable502
The configured Prometheus server is not responding.
HintCheck that Prometheus is running and reachable at the configured URL.
MTR003Missing Metrics Query400
The required query parameter is missing for the metrics endpoint.
HintProvide a PromQL query parameter.
MTR004Invalid Metrics Step400
The step parameter is outside the allowed range.
HintUse a step value between 5 and 300 seconds.
MTR005Too Many Metrics Streams429
The maximum number of concurrent metrics stream connections has been reached.
HintClose an existing metrics stream connection before opening a new one.
MTR006Missing Label Name400
The label name path parameter is missing.
HintProvide a label name in the URL path.
MTR007Prometheus Request Failed500
Failed to create the request to the Prometheus server.
HintThis is a server-side error. Check the Cetacean logs for details.

LOGLog streaming

LOG001Too Many Log Streams429
The maximum number of concurrent log stream connections has been reached.
HintClose an existing log stream before opening a new one.
LOG002Invalid Stream Parameter400
The stream parameter must be either stdout or stderr.
HintUse stream=stdout or stream=stderr.
LOG003Invalid After Parameter400
The after parameter must be an RFC 3339 timestamp or a Go duration string.
HintUse a format like 2024-01-01T00:00:00Z or 1h30m.
LOG004Invalid Before Parameter400
The before parameter must be an RFC 3339 timestamp or a Go duration string.
HintUse a format like 2024-01-01T00:00:00Z or 1h30m.
LOG005Before Not Supported For SSE400
The before parameter is not supported for SSE log streams because they are open-ended.
HintRemove the before parameter when using SSE, or use a JSON request instead.
LOG006Log Retrieval Failed500
Failed to retrieve logs from the Docker Engine.
HintCheck that the service or task still exists and the Docker Engine is reachable.
LOG007Log Parse Failed500
The logs were retrieved but could not be parsed.
HintThis is a server-side error. Check the Cetacean logs for details.
LOG008Log Stream Failed500
Failed to open the log stream from the Docker Engine.
HintCheck that the service or task still exists and the Docker Engine is reachable.
LOG009Too Many Log Reads429
The maximum number of concurrent log reads has been reached.
HintRetry after the time the Retry-After header names.

SSESSE connections

SSE001Too Many SSE Connections429
The maximum number of concurrent SSE connections has been reached, for the server or for this caller.
HintClose an existing SSE connection before opening a new one.

ENGDocker Engine

ENG001Docker Engine Unavailable503
The Docker Engine is not responding. The daemon may be stopped, restarting, or the socket may be unreachable.
HintCheck that the Docker daemon is running and that Cetacean has access to the Docker socket.
ENG002Docker Version Check Failed503
Could not determine the latest Docker Engine version from the GitHub API.
HintThis is a transient network error. Try again later.
ENG003Docker Validation Error400
The Docker Engine rejected the request due to invalid arguments.
HintCheck the request parameters for correctness.
ENG004Docker Engine Error500
An unexpected error occurred while communicating with the Docker Engine.
HintCheck the Cetacean and Docker daemon logs for details.
ENG005Docker Engine Timeout504
The Docker Engine did not answer within the time Cetacean allows for the operation.
HintCheck the daemon's load and logs, then retry.
ENG006Cluster Re-sync Failed502
Cetacean could not read the cluster from the Docker Engine. The detail names what each list answered.
HintCheck that docker.host points at a swarm manager and that the swarm has a leader.

SWMSwarm operations

SWM001Swarm API Not Available501
The swarm API is not available. This node may not be a swarm manager, or the Docker Engine may not support swarm mode.
HintEnsure Cetacean is connected to a swarm manager node.
SWM002Swarm Inspect Failed503
Failed to inspect the current swarm state. The swarm may be temporarily unavailable.
HintCheck that the swarm is healthy and retry the operation.
SWM003Swarm Update Failed500
The swarm configuration update failed.
HintCheck the Cetacean and Docker daemon logs for details.
SWM004Disk Usage Not Available501
Disk usage information is not available from the Docker Engine.
HintEnsure Cetacean is connected to a Docker Engine that supports the disk usage API.
SWM005Disk Usage Failed500
Failed to retrieve disk usage information from the Docker Engine.
HintCheck the Docker daemon logs for details.
SWM006Token Rotation Failed500
Failed to rotate the swarm join token.
HintCheck the Docker daemon logs for details.
SWM007Unlock Key Rotation Failed500
Failed to rotate the swarm unlock key.
HintCheck the Docker daemon logs for details.
SWM008Swarm Unlock Failed500
Failed to unlock the swarm with the provided key.
HintVerify the unlock key is correct and try again.
SWM009Unlock Key Retrieval Failed500
Failed to retrieve the swarm unlock key.
HintCheck the Docker daemon logs for details.
SWM010Unlock Key Required400
The unlock key is required to unlock the swarm.
HintProvide the unlockKey field in the request body.
SWM011Invalid Token Target400
The token rotation target must be either worker or manager.
HintUse target=worker or target=manager.

PLGPlugin operations

PLG001Plugin List Failed500
Failed to list plugins from the Docker Engine.
HintCheck that the Docker daemon is running and reachable.
PLG002Plugin Remote Required400
The remote field is required for plugin operations.
HintProvide the remote field specifying the plugin image reference.
PLG003Plugin Privilege Check Failed500
Failed to check the required privileges for the plugin.
HintCheck the Docker daemon logs for details.
PLG004Plugin Not Found404
The requested plugin does not exist on this Docker host.
HintCheck the plugin name and verify it is installed.
PLG005Plugin Privileges Required400
An install or upgrade must name the privileges it grants.
HintSend the privileges POST /plugins/privileges returned for this remote.
PLG006Plugin Privileges Changed409
The plugin now requires different privileges from the ones the request grants.
HintCheck the privileges again with POST /plugins/privileges and review the new set.

NODNode operations

NOD001Node Not Down409
The node cannot be removed in its current state. A node must be down before it can be removed from the swarm, and a manager must first be demoted to worker.
HintDemote the node if it is a manager. Then have the node leave the swarm or stop it so it goes down, or use force removal to remove a worker immediately. Draining a node does not take it down.
NOD002Node Version Conflict409
The node was modified by another client between the time it was read and the time the update was submitted.
HintReload the node and retry the operation.
NOD003Node Not Found404
The specified node does not exist in the swarm.
HintCheck the node ID or hostname and try again.
NOD004Invalid Availability Value400
The availability value must be one of: active, drain, pause.
HintUse availability=active, availability=drain, or availability=pause.
NOD005Invalid Role Value400
The role value must be one of: worker, manager.
HintUse role=worker or role=manager.

SVCService operations

SVC001Service Version Conflict409
The service was modified by another client between the time it was read and the time the update was submitted.
HintReload the service and retry the operation.
SVC002Service In Use409
The service cannot be removed because it is still referenced by other resources or managed by a stack.
HintRemove the stack that manages this service, or detach the service from the stack first.
SVC003Service Not Found404
The specified service does not exist in the swarm.
HintCheck the service ID or name and try again.
SVC004Replicas Required400
The replicas field is required for this operation.
HintProvide the replicas field in the request body.
SVC005Cannot Scale Global Service400
Global-mode services run exactly one task per node and cannot be scaled manually.
HintTo change the number of tasks, switch the service to replicated mode first.
SVC006Image Required400
The image field is required for service image updates.
HintProvide the image field in the request body.
SVC007No Previous Spec400
The service has no previous specification to rollback to.
HintRollback is only available after at least one update has been applied to the service.
SVC010Invalid Endpoint Mode400
The endpoint mode must be one of: vip, dnsrr.
HintUse mode=vip or mode=dnsrr.
SVC011Invalid Resource Specification400
The merged resource specification is not valid.
HintCheck the resource limits and reservations in the request body.
SVC012Invalid Update Policy400
The merged update policy specification is not valid.
HintCheck the update policy fields in the request body.
SVC013Invalid Rollback Policy400
The merged rollback policy specification is not valid.
HintCheck the rollback policy fields in the request body.
SVC014Invalid Healthcheck400
The merged healthcheck specification is not valid.
HintCheck the healthcheck fields in the request body.
SVC015Config Missing Required Fields400
Each config reference must include configID and configName.
HintProvide both configID and configName for every config entry.
SVC016Secret Missing Required Fields400
Each secret reference must include secretID and secretName.
HintProvide both secretID and secretName for every secret entry.
SVC017Network Missing Target400
Each network attachment must include a target network ID.
HintProvide the target field for every network entry.
SVC018Invalid Patch Result400
The JSON patch produced an invalid result that could not be applied.
HintCheck the patch operations for correctness.
SVC019Invalid Log Driver Specification400
The merged log driver specification is not valid.
HintCheck the log driver name and options in the request body.
SVC020Port Missing Target400
A published port must name the container port it forwards to.
HintSet TargetPort to a non-zero container port for every port entry.
SVC021Unknown Attachment400
A secret, config, or network the request attaches is not known to the cluster.
HintCheck the ID. A resource created outside Cetacean can take a moment to appear; retry shortly.

TSKTask operations

TSK001Task Already Removed409
The task could not be removed because the Docker Engine no longer tracks it.
HintThe task may have already been cleaned up. Refresh the page to see the current state.
TSK002Task Not Found404
The specified task does not exist.
HintCheck the task ID and try again. Tasks are ephemeral and may have been cleaned up.

STKStack operations

STK001Stack Not Found404
The specified stack does not exist. Stacks are derived from service labels and may disappear when all services in the stack are removed.
HintCheck the stack name and try again.

VOLVolume operations

VOL001Volume In Use409
The volume cannot be removed because it is in use: a local volume is mounted by one or more containers, or a cluster volume is still published to a node.
HintStop or remove the containers or services using this volume first. Force removal does not override a container using a local volume, but deletes a cluster volume even while it is in use.
VOL002Volume Not Found404
The specified volume does not exist.
HintCheck the volume name and try again.

NETNetwork operations

NET001Network Has Active Endpoints409
The network cannot be removed because it has active endpoints from running containers or services.
HintDisconnect or remove the services and containers attached to this network first.
NET002Network Not Found404
The specified network does not exist.
HintCheck the network ID and try again.

CFGConfig operations

CFG001Config In Use409
The config cannot be removed because it is referenced by one or more services.
HintRemove the config reference from all services before deleting it.
CFG002Config Not Found404
The specified config does not exist.
HintCheck the config ID and try again.
CFG003Config Name Conflict409
A config with this name already exists.
HintChoose a different name or remove the existing config first.
CFG004Invalid Config400
The config creation request is invalid.
HintProvide a non-empty name and valid base64-encoded data.
CFG005Config Version Conflict409
The config was modified concurrently.
HintRetry the operation with the latest version.

SECSecret operations

SEC001Secret In Use409
The secret cannot be removed because it is referenced by one or more services.
HintRemove the secret reference from all services before deleting it.
SEC002Secret Not Found404
The specified secret does not exist.
HintCheck the secret ID and try again.
SEC003Secret Name Conflict409
A secret with this name already exists.
HintChoose a different name or remove the existing secret first.
SEC004Invalid Secret400
The secret creation request is invalid.
HintProvide a non-empty name and valid base64-encoded data.
SEC005Secret Version Conflict409
The secret was modified concurrently.
HintRetry the operation with the latest version.