Learn
Reference
Examples
Learn
Reference
Examples

Troubleshoot

This section is meant to be consulted reactively: something broke, you have an error message or a wrong-looking result, and you want the shortest path back to a working state. It is not a tutorial. Each page is a lookup table — find the symptom, read the cause, apply the fix.

If you're still learning the model rather than recovering from a problem, start with Core Concepts or the Quick Start instead.

How to use this section

  1. Match the symptom. Use the index below to jump to the page whose symptoms look like yours.

  2. Read the cause, not just the fix. Most of these errors recur because of a misconfiguration that the fix only patches. The cause column tells you what to change so it stops happening.

  3. Turn on debug output. Almost every CLI problem gets clearer with verbose errors. Set TERRANTULA_DEBUG=1 before re-running any command — the CLI then prints the full error body (and stack traces for non-API errors) instead of the one-line summary.

    TERRANTULA_DEBUG=1 terrantula import terraform --state ./terraform.tfstate --config terrantula.yaml

  4. Add --json when you need a machine-readable failure. Diagnostic commands like terrantula github diagnose --json emit a structured report you can grep or pipe.

Most "it didn't do anything" reports are placement or scope, not bugs

Terrantula sits on top of your Terraform runner. It never runs terraform apply, never hosts your state, and the dashboard is a read-only projection. If something "didn't apply," the question is almost always which PR did it open (or fail to open) — see Action/PR debugging.

Symptom index

If you see…Go to
Error 401 / no API token provided / Run terrantula login firstCommon errors → Auth & config
No project specified / No org specifiedCommon errors → Project & org resolution
Error 422 / Error 404 from apply or an SDK callCommon errors → Apply failures
Dashboard won't start / port in useCommon errors → Dashboard
warn: unmatched TF resource … / resources missing from the graphImport/ingest issues → Unmatched resources
Failed to parse TF state / Invalid mapping configImport/ingest issues → Parse failures
TFC state source … requires a token / S3 / aws CLI errorsImport/ingest issues → Remote state
duplicate entity …Import/ingest issues → Duplicates
import-atmos found 0 stacks / nested-layout warningImport/ingest issues → Atmos imports
Action fired but no PR appearedAction/PR debugging → No PR opened
ActionRun stuck in running after the PR mergedAction/PR debugging → Run stuck running
GitHub App "not configured" / installations missingAction/PR debugging → github diagnose
Entities show stale / missing drift statusDrift & state issues → Sync-stamp drift
Re-import doesn't update a drifted entityDrift & state issues → Reconciliation policy
The graph disagrees with your Terraform stateDrift & state issues → Source of truth

The four pages

  • Common errors — auth, project/org resolution, apply/validation failures, and the dashboard.
  • Import/ingest issues — Terraform state + Atmos stack ingestion: parse errors, unmatched resources, duplicates, remote state.
  • Action/PR debugging — Actions that don't open the PR you expected, plus trigger and webhook diagnosis.
  • Drift & state issues — drift status, reconciliation policies, and reconciling the graph with your state backend.
ON THIS PAGE