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​

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​

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​

decoding: depends_on expected a map, got slice

The depends_on functionality originally existed only under settings.spacelift.depends_on and was a list of other components that the current component depends on.

We have since updated depends_on to be more generic and be directly under settings.depends_on (so it can also be used in GitHub Actions and other tools).

The updated key is now a map (rather than a list). If you see this error, it means that someone put a depends_on block directly under settings but added it as a list (rather than a map as the new config requires).

The solution is to move it under settings.spacelift.depends_on (legacy, deprecated, not recommended) or update the dependencies to be a map.

components:
  terraform:
    top-level-component2:
      metadata:
        component: "top-level-component1"
      settings:
        spacelift:
          workspace_enabled: false
        depends_on:
          1:
            # If the `context` (namespace, tenant, environment, stage) is not provided,
            # the `component` is from the same Atmos stack as this component
            component: "test/test-component"
          2:
            # If the `context` (namespace, tenant, environment, stage) is not provided,
            # the `component` is from the same Atmos stack as this component
            component: "test/test2/test-component-2"
          3:
            file: "tests/fixtures/scenarios/complete/components/terraform/mixins/introspection.mixin.tf"
          4:
            folder: "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​

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:

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​

In atmos.yaml, set components.terraform.init_run_reconfigure to true:

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

This will tell Atmos to run terraform init -reconfigure when executing Terraform commands. The -reconfigure option disregards any existing backend configuration and configures a new backend, preventing migration of any existing state.

tip

For more information, refer to: