# Migrate Legacy settings.depends_on

:::warning Deprecated

`settings.depends_on` is supported only for backward compatibility. New and updated configurations must use [`dependencies.components`](/stacks/dependencies/components). Use [`dependencies.files`](/stacks/dependencies/components#file-and-folder-dependencies) and [`dependencies.folders`](/stacks/dependencies/components#file-and-folder-dependencies) for external paths.

The same map is also accepted directly on the component (without the `settings` wrapper),
also for backward compatibility only. Both forms remain fully functional — no dependency
edges are dropped — but [`atmos validate stacks`](/cli/commands/validate/stacks) prints a
non-failing warning wherever either legacy form is used, naming `dependencies.components`
as the replacement.

:::

## Migration

Replace the map under `settings.depends_on` with a list under `dependencies.components`. Change `component` to `name`, and replace the legacy context fields with an explicit `stack` value, optionally constructed with a Go template.

**File:** `Before (legacy)`

```
components:
  terraform:
    app:
      settings:
        depends_on:
          network:
            component: vpc
          database:
            component: rds
            tenant: tenant1
            environment: ue2
            stage: prod
```

**File:** `After (current)`

```
components:
  terraform:
    app:
      dependencies:
        components:
          - name: vpc
          - name: rds
            stack: tenant1-ue2-prod
```

## List Form

`settings.depends_on` is also accepted as a list, which is the older legacy shape. Each entry is a component name, or an object with `component` and an optional `stack`. Context fields such as `tenant` or `stage` are accepted only in the map form:

**File:** `List form (legacy)`

```
components:
  terraform:
    app:
      settings:
        depends_on:
          - component: vpc
          - component: rds
            stack: tenant1-ue2-prod
```

`atmos doctor --fix` migrates the list form to `dependencies.components` when every entry names a literal `component` and an optional `stack`; the map form is reported for a manual change. It rejects the repair when the migration would change which components any component depends on, for example when an inherited base declares a list and the inheriting component declares its own. The migration intentionally adopts the required semantics of `dependencies.components`: a missing or disabled target, which the list form only warns about, is reported as an error after the migration instead of blocking it, so you can fix the reference. See [`atmos doctor`](/cli/commands/doctor).

## Field Mapping

| Legacy field | Current form |
| --- | --- |
| `component` | `name` |
| `namespace`, `tenant`, `environment`, `stage` | `stack`, optionally using a Go template |
| `file` | `dependencies.files` |
| `folder` | `dependencies.folders` |

The new format can also declare a cross-type dependency with `kind`. See [Component Dependencies](/stacks/dependencies/components) for the complete schema, merge behavior, and examples.