Error Code Catalog
This document lists all error codes used by Phala Cloud API. Error codes follow the formatERR-{MODULE}-{CODE} where:
- MODULE: Two-digit module identifier (01, 02, 03, …)
- CODE: Three-digit sequential error number within the module
Modules
- Module 01 - CVM API / Preflight
- Module 02 - Inventory
- Module 03 - CVM Operations
- Module 04 - Workspace
- Module 05 - Credentials
- Module 06 - Authentication (OAuth redirect errors — not returned as JSON API responses)
Module 01: CVM API / Preflight
| Error Code | Exception Class | Message |
|---|---|---|
ERR-01-001 | NodeNotFoundError | The requested node is not available Raised when specified node is not found |
ERR-01-002 | ComposeFileRequiredError | The request contains invalid parameters Raised when compose_file is required but not provided |
ERR-01-003 | InvalidComposeFileError | The Docker Compose file contains errors Raised when Docker Compose file is invalid |
ERR-01-004 | DuplicateCvmNameError | (dynamic: A CVM with name ’…) Raised when a CVM name already exists in the workspace (HTTP 409) |
ERR-01-005 | HashRegistrationRequired | Compose hash registration required on-chain Raised by an onchain KMS compose update when the new compose hash is not yet on DstackApp.allowedComposeHashes; the response carries commit_token, commit_url, and the on-chain action needed to complete the prepare-approve-commit flow (HTTP 465) |
ERR-01-006 | HashInvalidOrExpired | The provided compose hash is invalid or has expired Raised at commit time when the commit token is unknown, has expired (14-day TTL), has been superseded by a newer prepare for the same CVM, or the compose hash bound to the token no longer matches the compose file currently saved for this CVM — re-run prepare to recover (HTTP 466) |
ERR-01-007 | TxVerificationFailed | Transaction verification failed Raised at commit time when the supplied transaction_hash cannot be verified against the expected addComposeHash state change — the receipt is missing, the transaction reverted, or it did not target the expected DstackApp contract (HTTP 467) |
ERR-01-008 | HashNotAllowed | The compose hash is not allowed by the on-chain contract Raised at commit time when DstackApp.allowedComposeHashes(bytes32) returns false for the target hash — typically because the Phase 2 approval transaction has not actually landed on the expected contract, or landed on the wrong contract (HTTP 468) |
Module 02: Inventory
| Error Code | Exception Class | Message |
|---|---|---|
ERR-02-001 | InstanceTypeNotFoundError | The requested instance type does not exist Raised when a requested instance type is not found. |
ERR-02-002 | ResourceNotAvailableError | No available resources match your requirements Raised when no suitable resources are found |
ERR-02-003 | InsufficientVcpuError | The selected node does not have enough CPU capacity Raised when teepod has insufficient vCPU resources. |
ERR-02-004 | InsufficientMemoryError | The selected node does not have enough memory Raised when teepod has insufficient memory resources. |
ERR-02-005 | InsufficientSlotsError | The selected node has reached its maximum capacity Raised when teepod has no available CVM slots. |
ERR-02-006 | GpuAllocationError | The selected node does not have enough GPU resources Raised when GPU allocation fails |
ERR-02-007 | InsufficientGpuError | The selected node does not have enough GPU resources Raised when teepod has insufficient GPU resources. |
ERR-02-008 | InvalidRequestError | The request contains invalid parameters Raised when request parameters are invalid |
ERR-02-009 | IncompatibleConfigurationError | The configuration parameters are not compatible with each other Raised when resource configuration is not compatible |
ERR-02-010 | ImageNotFoundError | The requested operating system image is not available Raised when a requested OS image is not found. |
ERR-02-011 | KmsNotFoundError | The requested security configuration is not available on this node Raised when no matching KMS is found on teepod. |
ERR-02-012 | TeepodNotAccessibleError | The requested node is not available Raised when user doesn’t have permission to access a teepod. |
ERR-02-013 | OsImageNotCompatibleError | The requested operating system image is not available Raised when no compatible OS image is found. |
ERR-02-014 | NodeCapacityNotConfiguredError | The requested node is not available Raised when node capacity is not properly configured. |
ERR-02-015 | QuotaExceededError | Your account has reached its resource quota Raised when team resource quota would be exceeded. |
ERR-02-016 | GpuDeviceInUseError | GPUs are available but currently occupied at device level Raised when GPUs are available in database but occupied at device level. |
Module 03: CVM Operations
| Error Code | Exception Class | Message |
|---|---|---|
ERR-03-001 | CvmNotFoundError | The requested CVM was not found Raised when a CVM is not found by the given identifier (HTTP 404). |
ERR-03-002 | MultipleCvmsWithSameNameError | Multiple CVMs have the same name in this workspace Raised when multiple CVMs share the same name in a workspace. |
ERR-03-003 | CvmNotInWorkspaceError | No CVM found in this workspace Raised in admin contexts when a CVM exists but belongs to a different workspace — reveals the workspace mismatch (HTTP 404). |
ERR-03-004 | CvmNotInWorkspaceError | The requested CVM was not found Raised in non-admin contexts when a CVM belongs to a different workspace — message matches ERR-03-001 to avoid leaking CVM existence (HTTP 404). |
ERR-03-005 | CvmAccessDeniedError | The requested CVM was not found Raised when user lacks permission for a CVM operation — message intentionally matches ERR-03-001 to avoid revealing whether the CVM exists (HTTP 404). |
ERR-03-006 | ReplicaImageNotAvailableError | The source CVM’s OS image is not available on the target node Raised when the source CVM’s OS image is not available on the target node. |
ERR-03-007 | CvmAppIdConflictError | This app_id already has an active CVM with a different configuration. Provision again to get a new app_id, or use the existing CVM. Raised when app_id is already used by a different configuration in the same workspace (HTTP 409). |
ERR-03-008 | ReplicaSourceInstanceNotAccessibleError | The source CVM instance was not found in this workspace or access is denied Raised when the replica source CVM instance is not visible in the current workspace (HTTP 404). |
ERR-03-009 | ReplicaComposeHashRequiredError | This app has multiple live CVM instances. Please specify compose_hash to choose which revision to replicate. Raised when replicate needs an explicit compose_hash due to multiple live instances. |
ERR-03-010 | MultipleCvmsForIdentifierError | Multiple CVMs match this identifier in the workspace Raised when an identifier (e.g. app_id) matches multiple CVMs in a workspace. |
ERR-03-040 | ComposeFieldImmutableError | (dynamic: cannot be changed on an existing CVM…) A compose update changes a field that is fixed when the CVM is created. |
ERR-03-041 | ComposeFieldNotAllowedOnCreateError | tproxy_enabled cannot be set when creating a CVM. Use gateway_enabled instead. A create request sets tproxy_enabled, the legacy alias of gateway_enabled. |
ERR-03-042 | ComposeGpuPolicyNotAllowedError | requirements.gpu_policy is not enabled for this account or workspace. requirements.gpu_policy is set or changed without the compose_gpu_policy grant. |
ERR-03-043 | LaunchTokenHashMismatchError | requirements.launch_token_hash does not match this app’s launch token. requirements.launch_token_hash does not match the app’s launch token. |
ERR-03-044 | LaunchTokenConflictError | This app already has a different launch token. A create sends a launch token other than the one the app already has. |
ERR-03-045 | ComposeAdvancedNotAllowedError | (dynamic: is not enabled for this account or workspace…) A create uses a non-default runner or raw compose input without compose_advanced. |
ERR-03-046 | ComposeRunnerNotSupportedError | (dynamic: Runner …) The compose names a runner the dstack guest does not run. |
ERR-03-047 | ComposeFieldRequiredError | (dynamic: The …) The compose’s runner needs a field the caller did not send. |
ERR-03-048 | ComposeDataWipeNotConfirmedError | (dynamic: Turning on …) An update turns on a setting that wipes data on every boot without confirming it. |
ERR-03-049 | CvmAnnotationsNotEnabledError | CVM annotations are not enabled for this account or workspace. The cvm_annotations feature flag is off for the workspace and the caller. |
ERR-03-050 | CvmAnnotationsVmmUnsupportedError | (dynamic: The node runs dstack VMM …) The node’s dstack VMM predates per-VM annotations (added in 0.6.1). |
ERR-03-051 | CvmAnnotationsVmmRequestFailedError | (dynamic: The node could not read or update the CVM annotati…) The node’s VMM did not return or did not accept the CVM’s annotations. |
ERR-03-052 | CvmDraftNotFoundError | This CVM has no staged changes. The CVM has no draft to show, apply or discard. |
ERR-03-053 | CvmDraftOutdatedError | The CVM changed after these changes were staged. The CVM’s compose changed after its draft was opened; nothing was applied. |
ERR-03-054 | CvmDraftChangedError | The staged changes were changed by another request. Load them and try again. Another request changed the draft while this one ran, or after its apply was prepared. |
Module 04: Workspace
| Error Code | Exception Class | Message |
|---|---|---|
ERR-04-001 | InsufficientBalanceError | You need to top up your account before launching a CVM. Raised when account balance is too low |
ERR-04-002 | MaxCvmLimitError | Your account has reached the maximum number of instances Raised when VM count limit is reached |
ERR-04-003 | ResourceLimitExceededError | The requested resources exceed your account limits Raised when resource limits are exceeded |
Module 05: Credentials
| Error Code | Exception Class | Message |
|---|---|---|
ERR-05-001 | TokenLimitExceededError | (dynamic: You have reached the maximum of …) Raised when workspace token limit is exceeded |
ERR-05-002 | TokenRateLimitError | (dynamic: Rate limit exceeded: maximum …) Raised when token creation rate limit is exceeded |