Skip to main content

Debugging

Start by inspecting the configuration Atmos resolves for the failing component and stack. This separates configuration problems from errors returned by Terraform, CloudFormation, or another underlying tool.

Inspect Effective CLI Configuration​

Run from the same directory, with the same profile and environment, as the failing command:

atmos version
atmos describe config --format yaml

describe config shows the merged CLI configuration. Check base_path, component and stack paths, included/excluded stack paths, and the selected profile. A CLI configuration file (atmos.yaml) and a stack manifest serve different purposes; inspect each separately.

Trace a Component Value​

atmos describe component vpc -s dev --provenance

describe component shows the resolved component configuration. Provenance identifies the source of values so you can find which imported defaults or component overrides contributed to the result. Check vars, settings, metadata, and, for Terraform, backend and workspace.

Output inspection can evaluate functions that read state, contact services, or run commands such as !exec. When investigating parsing or configuration without resolving those functions, disable processing as shown below. Review output before sharing it: ordinary variables and store values may contain sensitive information.

Check Imports and Merging​

An _defaults.yaml file is a naming convention, not an automatic parent-directory inheritance rule. Follow the actual imports and component inheritance in the selected stack.

By default, maps merge and lists replace. For example:

# Imported defaults
vars:
  tags:
    owner: platform
    environment: dev
  zones: [a, b]
# Values in the importing stack
vars:
  tags:
    environment: production
  zones: [c]

The result retains tags.owner: platform, sets tags.environment: production, and replaces zones with [c]. An empty map does not clear inherited map keys. Check settings.list_merge_strategy if the project changes the default list behavior, and use provenance to verify the actual result. Locals are file-scoped and do not inherit across imports like vars.

Isolate Template and Function Evaluation​

Compare the resolved component with each processing stage disabled:

atmos describe component vpc -s dev --process-templates=false
atmos describe component vpc -s dev --process-functions=false
atmos describe component vpc -s dev --process-templates=false --process-functions=false

These flags are diagnostic controls for the describe command, not a way to make an invalid deployment valid. Inspect template inputs, YAML quoting, and the referenced component and stack names. A fallback in a value expression is not a guarantee that a missing stack or failed authentication will be ignored. For deployed-output lookups, confirm the producer exists and the reader has access; see sharing data and outputs.

Validate and Narrow the Failure​

atmos validate stacks

Stack validation checks configuration; it does not prove that remote resources, credentials, or outputs are available. If configuration resolves but the underlying tool fails, inspect that tool's diagnostic and the common errors guide. Use the profiling guide for slow operations.

Prepare a Minimal Reproduction​

Include the Atmos and underlying tool versions, exact command, working directory relative to the repository, selected profile/identity names, error text, and the smallest relevant atmos.yaml and stack manifests. Keep the imports and dependency relationships that trigger the problem. State the expected result and whether it happens locally, in CI, or both.

Remove credentials, private state, and organization-specific values before sharing. Preserve the structure and value types so others can reproduce the configuration behavior without access to your infrastructure.