The orchestrator returns errors as JSON:
{
"code": "<machine-readable>",
"message": "<human-readable>"
}
The CLI surfaces both, and adds a one-line hint when applicable.
Authentication
| Code | HTTP | What it means | Action |
|---|
unauthorized | 401 | Missing / invalid bearer token | Re-run artifacts login; check the JWT hasn't expired. |
forbidden | 403 | Token valid but lacks permission | The user (or service token) doesn't own the workspace. Check artifacts workspace list. |
Workspaces
| Code | HTTP | What it means | Action |
|---|
workspace_not_found | 404 | Identifier doesn't match an existing workspace | Confirm the <handle>/<name> is right; artifacts workspace list. |
workspace_exists | 409 | A workspace with that name already exists for this user | Pick a different name, or artifacts workspace delete <name> first. The 409 body includes an existing field with the live state, which artifacts workspace create uses to resume pending_format automatically. |
workspace_not_active | 409 | Tried to mount or format-completed against a workspace that's not active | If pending_format, re-run artifacts workspace create <name> to resume. If deleting / deleted, recreate. |
workspace_not_completable | 409 | /format-completed called on something other than pending_format | Almost always means the workspace is already active, in which case the orchestrator returns 200 idempotently via the active short-circuit. If you're seeing this 409, it's likely a stale CLI binary; reinstall. |
setting_key_missing | 422 | /format-completed called but no setting key in Redis under the workspace prefix | Phase 2 didn't actually run, or it ran against a different bucket. Re-run artifacts workspace create. |
Mount sessions
| Code | HTTP | What it means | Action |
|---|
metadata_acl_provisioning_failed | 500 | The orchestrator couldn't reach Redis to set up your per-session ACL | Transient. Retry in a few seconds. If it persists past 60 s, contact us; there's an alert on our side too. |
Validation
| Code | HTTP | What it means | Action |
|---|
invalid_request | 422 | Request body / params don't satisfy the schema | The message field has the specific complaint, e.g. storage.bucket is required or ttl_seconds must be between 60 and .... |
Internal
| Code | HTTP | What it means | Action |
|---|
internal_error | 500 | Unexpected server-side failure | Retry once. If it repeats, contact us with the timestamp + your workspace identifier. |
Client-side errors
These never have an HTTP code; the CLI surfaces them before the
request hits the orchestrator.
| Symptom | Hint |
|---|
path /mnt/work is already a mount point | artifacts unmount /mnt/work first. The CLI reads /proc/self/mountinfo to detect this. |
BYO mode requires ARTIFACTS_S3_ACCESS_KEY_ID and ARTIFACTS_S3_SECRET_ACCESS_KEY | Export them in your shell or run artifacts storage set --access-key-id ... --secret-access-key .... |
byo_env requires ARTIFACTS_S3_ACCESS_KEY_ID and ARTIFACTS_S3_SECRET_ACCESS_KEY (set them in the environment or run \artifacts storage set`)` | Same as above; the cache is also empty. |
bad jwt: ... (during login) | The token format doesn't match what the orchestrator expects. Check you pasted the whole thing, no truncation. |
Bucket / S3 errors during workspace create Phase 2
These come straight from juicefs's S3 backend; the message includes
the underlying S3 error code:
| What you'll see | Likely cause |
|---|
Object storage test failed: ... AccessDenied | Bucket policy doesn't grant your AK list/get/put. |
Object storage test failed: ... NoSuchBucket | Bucket name typo or wrong endpoint. |
Object storage test failed: ... InvalidAccessKeyId | AK/SK pair is wrong or expired. |
Object storage test failed: ... SignatureDoesNotMatch | Region mismatch (Tigris uses auto; AWS regions are us-west-1 etc.). |
Reproduce locally with aws s3 ls s3://<bucket>/ --endpoint-url <endpoint> to confirm before re-running workspace create.