#Common errors

Frequent CLI and API failures, organized by what you'll see in your terminal. For deeper verbose output on any command, set TERRANTULA_DEBUG=1 — the CLI then prints the full error body (API errors) or stack trace (local errors) instead of the one-line summary.

#Authentication and credentials

#Error: no API token provided

Symptom

Cause — terrantula login reads the token from the global --token flag or the TERRANTULA_TOKEN environment variable. It does not accept a --token after the login subcommand.

Fix — pass the token before the subcommand, or via the environment:

terrantula --token terr_xxxxxxxx login --base-url https://terrantula.example.com
# or
TERRANTULA_TOKEN=terr_xxxxxxxx terrantula login --base-url https://terrantula.example.com

The token is saved to your config file with 600 permissions. Only the prefix is ever displayed; the full value is never logged.

#Error 401 on any authenticated command

Symptom — a project- or org-scoped command returns Error 401: ....

Cause — the saved token is missing, expired, revoked, or doesn't carry the permission the route requires (project API tokens are RBAC-scoped — a read-only token can't write).

Fix

1. Re-run terrantula login with a valid token.
2. Confirm the token has the right role for the operation. Write operations need a token whose role grants the relevant *:write permission; see RBAC roles & permissions.
3. If you self-host, confirm the CLI's base URL points at the right server (terrantula login --base-url …).

#Run terrantula login first (no API token + base URL configured)

Symptom — emitted by diagnostic commands such as terrantula github diagnose.

Cause — no base URL and token are saved, and none were passed via --base-url / --token.

Fix — run terrantula login (with a global --token and --base-url) once; subsequent commands reuse the saved config.

#Project and org resolution

#No project specified

Symptom

Cause — commercial (server-backed) commands need a project ID. The CLI resolves it in this order: --project flag → global --project → TERRANTULA_PROJECT_ID env → the default set by terrantula use.

Fix — set a default for the session, or pass the flag explicitly:

terrantula use <project-id>          # saves the default
terrantula import terraform --project <project-id> --state … --config …

In CI, prefer the env var so no saved login is required:

export TERRANTULA_PROJECT_ID=<project-id>
export TERRANTULA_ORG_ID=<org-slug>

#No org specified

Symptom

Cause — same resolution chain as project, for the org slug: --org → global --org → TERRANTULA_ORG_ID → saved org.

Fix — set TERRANTULA_ORG_ID or pass --org <slug>. Note: import-atmos defaults the org/project to the local-mode sentinel terrantula when none is given, so it can run against a local DB without a login; import terraform does not — it always requires a real org and project because it's a server-backed flow.

#Apply and validation failures

#Error 422 from an apply or SDK call

Symptom — the server rejects an apply bundle, or a specific item appears under Failed in the apply output:

Cause — the declaration is structurally valid YAML but violates a server-side rule: an unknown entityType, an invalid lifecycle state transition, a relationship pointing at a non-existent entity, or a constraint violation.

Fix

1. Read the per-item error string — it names the field that failed.

2. Confirm the referenced kinds exist. Apply the catalog (EntityTypes, RelationshipTypes, Cells) before the data (Entities, Relationships). The Catalog Schema Reference documents the required fields per kind.

3. Re-run with --dry-run (alias --plan) to see the computed diff without writing:

   terrantula apply --file blueprint.yaml --dry-run

#Error 404 from a project-scoped call

Symptom — Error 404: ... from an entity/relationship/cell operation.

Cause — usually a wrong org/project/env triple, or referencing an entity by a name that doesn't exist in that environment. Environment matters: every data call is env-scoped and defaults to default.

Fix — confirm --env (or TERRANTULA_ENV_NAME) matches the environment the data actually lives in, and that the org/project pair is correct.

#Hint: this cell's membership is computed from a property

Symptom — adding a member to a cell fails with a CELL_MEMBERSHIP_DERIVED hint.

Cause — the cell is a derived cell: membership is computed from an entity property, not set directly. The UI is a read-only projection and the API enforces the same rule.

Fix — change the underlying property through an Action (which opens a PR), not by adding the member directly:

terrantula actions run <action> …

Only explicit cells accept direct membership writes. See Cell.

#Dashboard won't start

#error: --port must be a number between 1 and 65535

Cause — a non-numeric or out-of-range --port value.

Fix — pass a valid port, or omit --port to bind a random free port:

terrantula dashboard --port 4173

#The dashboard fails to bind / address already in use

Symptom — terrantula dashboard exits with a bind error mentioning the port.

Cause — another process holds the port you requested.

Fix — drop --port so the CLI picks a free port automatically, or choose a different one. The dashboard prints the resolved URL (✓ Dashboard ready at http://…) on success.

#Related

• Import/ingest issues — state and config parse problems.
• SDK error handling — the TerrantulaError shape (status, body, message).
• Common CLI flows — the canonical command invocations.
• RBAC roles & permissions — what each token role can do.