# Common Errors

## Error Monitoring

For organizations running Atmos at scale, consider enabling [Error Handling & Monitoring](/cli/configuration/errors) 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`

```console
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.

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

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

```console
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`.

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

### Error: `depends_on expected a map, got slice`

```console
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.

```yaml
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:

- [`atmos describe affected` CLI command](/cli/commands/describe/affected)
- [`atmos describe dependents` CLI command](/cli/commands/describe/dependents)

:::

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

```console
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:

```console
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`:

```yaml
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:

- [`terraform init` command](https://developer.hashicorp.com/terraform/cli/commands/init)
- [Terraform Backend Initialization](https://developer.hashicorp.com/terraform/cli/commands/init#backend-initialization)
- [Atmos CLI configuration](/cli/configuration/)
- [Atmos Terraform/OpenTofu commands](/cli/commands/terraform/usage/)

:::