Skip to main content

Common Errors

Error Monitoring​

For organizations running Atmos at scale, consider enabling Error Handling & Monitoring to track failures across your infrastructure pipelines with Sentry integration.

Common Mistakes​

  • Running out of date version of atmos with newer configuration parameters
  • An atmos.yaml with incorrect stacks.stack_name pattern (often due to copy pasta)

Common Errors​

Here are some common errors that can come up.

Error: stack name pattern must be provided​

Terminal
stack name pattern must be provided in 'stacks.name_pattern' config or 'ATMOS_STACKS_NAME_PATTERN' ENV variable

This means that you are probably missing a section like this in your atmos.yml. See the instructions on CLI Configuration for more details.

stacks:
  name_pattern: "{tenant}-{environment}-{stage}"

Error: The stack name pattern ... does not have a tenant defined​

Terminal
The stack name pattern '{tenant}-{environment}-{stage}' specifies 'tenant', but the stack ue1-prod does not have a tenant defined

This means that your name_pattern declares a tenant is required, but not specified in the Stack configurations. Either specify a tenant in your vars for the Stack configuration, or remove the {tenant} from the name_pattern.

stacks:
  name_pattern: "{tenant}-{environment}-{stage}"

Error: depends_on expected a map, got slice​

Terminal
decoding: depends_on expected a map, got slice

settings.spacelift.depends_on and settings.depends_on are legacy dependency formats. A list under settings.depends_on does not match the legacy map schema.

The recommended fix is to migrate the dependency declaration to dependencies.components; do not move it to a legacy Spacelift setting.

components:
  terraform:
    top-level-component2:
      metadata:
        component: "top-level-component1"
      dependencies:
        components:
          - name: "test/test-component"
          - name: "test/test2/test-component-2"
        files:
          - tests/fixtures/scenarios/complete/components/terraform/mixins/introspection.mixin.tf
        folders:
          - tests/fixtures/scenarios/complete/components/helmfile/infra/infra-server
      vars:
        enabled: true
tip

For more information, refer to:

Error: A change in the backend configuration has been detected, which may require migrating existing state​

Terminal
A change in the backend configuration has been detected, which may require migrating existing state

The Terraform/OpenTofu error means Terraform noticed that your backend configuration (the section in your code that defines where and how Terraform stores state) has changed compared to what’s currently in use..

Why it happens​

Terraform keeps its state in a backend (for example, S3, local, remote, Terraform Cloud, etc.). If you update the backend configuration in your code — for example:

  • Switching from local to s3
  • Changing the bucket, key, or region for an S3 backend
  • Modifying a prefix or workspace config in Terraform Cloud
  • Adjusting encryption or locking settings
  • Terraform detects that the state might need to be migrated from the old backend to the new one.

What Terraform expects​

When this happens, Terraform doesn’t automatically move state — it prompts you to confirm migration. Typically, you’ll see a message like:

Terminal
Do you want to copy existing state to the new backend?
Enter "yes" to copy and "no" to start with an empty state.

If you type yes, Terraform migrates the state (so you keep your existing resources). If you type no, Terraform initializes a fresh, empty state in the new backend (dangerous unless intentional).

How to resolve​

First inspect the resolved backend and workspace with atmos describe component <component> -s <stack>. Decide whether you are selecting an existing deployment or intentionally moving its state:

SituationNext step
Switching between component instances with different, already-correct backend settingsReinitialize the working directory for the selected backend with -reconfigure; do not copy another instance's state into it.
Intentionally moving the same deployment to another backend locationBack up state and follow the backend's migration procedure. Terraform's init -migrate-state attempts to copy existing state; -reconfigure does not.
A rename or configuration edit unexpectedly changed the backend or workspaceRestore the intended state identity before proceeding. See renaming Terraform stacks.

For the first case, if your workflow needs reconfiguration when switching instances, configure Atmos to run terraform init -reconfigure:

components:
  terraform:
    # Can also be set using 'ATMOS_COMPONENTS_TERRAFORM_INIT_RUN_RECONFIGURE' ENV var, or '--init-run-reconfigure' command-line argument
    init_run_reconfigure: true

The -reconfigure option discards the working directory's previous backend configuration without migrating state. It is appropriate only when the selected backend already identifies the intended deployment. It does not repair a changed state key or move resources between workspaces. For an intentional migration, avoid forcing reconfiguration and follow the underlying tool's backend initialization procedure.

After initialization, review a plan. Unexpected creation of existing resources is a reason to recheck the backend and workspace, not to apply the plan.

tip

For more information, refer to: