#Import/ingest issues

Problems while running terrantula import terraform or terrantula import-atmos. The import maps your existing state into entities and relationships; most failures here are mapping-config or source-access problems, not graph problems.

terrantula import terraform --state ./terraform.tfstate --config terrantula.yaml --dry-run

#Unmatched resources

#warn: unmatched TF resource …

Symptom

…and the resource doesn't appear in the dashboard.

Cause — your mapping config has no mappings rule for that Terraform resource type. By default unmatched resources are skipped with a warning, so the import succeeds but the graph is incomplete.

Fix — add a mapping rule for the resource type, then re-import:

# terrantula.yaml
entity_types:
  - name: Database
    tf_resource_types:
      - aws_db_instance

If a resource type is intentionally not part of your fleet model, add it to ignore: so it stops warning:

ignore:
  - aws_cloudwatch_log_group

#Unmatched resources should be a hard error

Symptom — you want CI to fail when a new resource type appears with no mapping.

Fix — pass --strict. Unmatched resources become errors (exit code 1) instead of warnings, so an un-modeled resource type can't silently slip through.

terrantula import terraform --state … --config … --strict

#Nothing imported / dashboard empty

Cause — every resource was unmatched (no rules matched any resource type) or every resource type was in ignore:.

Fix — run with --dry-run and read the mapped-count line (Mapped N entities and M relationships). If N is 0, your mappings keys don't match the actual type values in the state. Confirm the exact resource type strings — they're the second field in each warning (type=aws_db_instance).

#State and config parse failures

#Failed to parse TF state …

Symptom

Cause — the file isn't valid Terraform state JSON: it's truncated, it's an HCL .tf file rather than a state file, or it's a state-versioned format the parser doesn't recognize.

Fix — confirm you pointed --state at a real state file. Generate a fresh one with terraform state pull > terraform.tfstate and re-import that. State is JSON; a .tf source file will not parse.

#Failed to parse mapping config … /Invalid mapping config …

Symptom

Cause — the first form is a YAML syntax error; the second means the YAML parsed but doesn't match the expected schema (e.g. a misspelled top-level key, a mapping value of the wrong type).

Fix — fix the indentation/quoting (YAML error) or the structure (schema error). The minimal valid shape is:

entity_types:
  - name: Server
    tf_resource_types:
      - aws_instance

relationship_types: []

#Unsupported extends entry … /Unknown starter … /Cyclic 'extends:' detected

Cause — the config's extends: references a starter that isn't bundled, doesn't exist, or forms a cycle.

Fix — only bundled starters (prefixed terrantula/starters/…) are supported. The error message lists the available starter names — copy one exactly, or remove the extends: entry. A cycle (a -> b -> a) means two starters extend each other; break the loop.

#Remote state (S3 and TFC)

#TFC state source … requires a token

Symptom

Cause — a tfc:// or https://app.terraform.io/… state URI was supplied with no token to authenticate against Terraform Cloud / HCP Terraform.

Fix — supply a token via any of the three accepted sources (the env vars are checked automatically):

terrantula import terraform --state tfc://my-org/my-workspace --config … --tfc-token "$TFC_TOKEN"
# or rely on the standard Terraform env var:
export TF_TOKEN_app_terraform_io=…

#Unsupported https/http state URI …

Cause — an https:// URL was passed that isn't a recognized TFC workspace URL.

Fix — use the canonical TFC URL form https://app.terraform.io/app/<org>/workspaces/<workspace>, the shorthand tfc://<org>/<workspace>, or download the state and pass a local path / s3:// URI.

#Malformed s3:// URI … /Failed to invoke 'aws' CLI

Symptom

Cause — S3 state reads shell out to the aws CLI. The first error is a malformed URI (missing key); the second means the aws binary isn't on PATH or isn't configured.

Fix — use the full s3://bucket/path/terraform.tfstate form, and make sure the AWS CLI is installed and its credentials/region are configured (the import inherits your shell's AWS environment). A non-zero exit from aws s3 cp includes the CLI's stderr — read it for the underlying access/permission cause.

#Duplicate entities

#duplicate entity …

Symptom

Cause — two or more Terraform resources mapped to the same (entityType, name). This usually means the name template doesn't include enough of the resource's identity (e.g. naming by resource type instead of by a unique attribute).

Fix — make the name template unique per resource, or accept last-writer-wins by passing --allow-duplicates (the last mapped resource wins for the colliding name).

#Atmos stack imports

#import-atmos found 0 stacks

Symptom

Cause — import-atmos reads the top level of the directory only, but your Atmos repo nests stack manifests in subdirectories.

Fix — add --recursive to walk subdirectories:

terrantula import-atmos ./stacks --entity-type Tenant --name "{{ vars.customer_id }}" --recursive

#<dir> is not a directory

Cause — the <stacks-dir> argument points at a file or a non-existent path.

Fix — pass the directory that contains your stack manifests, not an individual manifest file.

#Atmos entities have wrong or empty names

Cause — the --name template references a stack variable that doesn't exist on every stack, so some entities get empty/wrong names.

Fix — point --name at a var present on every stack (e.g. "{{ vars.customer_id }}"). Preview the result first with --plan — it prints each Entity <type>/<name> line so you can confirm the names before writing.

#Related

• Common CLI flows — full import invocations (local, S3, TFC, multi-state, Atmos).
• Common errors — auth, project/org, and apply failures that can also surface during import.
• Import your TF state — the guided first-import walkthrough.
• Catalog YAML guide — the mapping and catalog YAML shapes.
• Drift & state issues — what happens after a successful import when the source changes.