Claude-skill-registry debugging-atmos

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/debugging-atmos" ~/.claude/skills/majiayu000-claude-skill-registry-debugging-atmos && rm -rf "$T"

manifest: skills/data/debugging-atmos/SKILL.md

Debugging Atmos

Techniques for troubleshooting Atmos configuration and deployment issues.

Quick Debugging Commands

# See the fully-resolved YAML for a component
atmos describe component <component> -s <stack>

# Enable verbose debug logging
ATMOS_LOGS_LEVEL=debug atmos terraform plan <component> -s <stack>

# Validate all stack configurations
atmos validate stacks

# Reset local state and cache
atmos terraform clean <component> -s <stack>

Inspecting Resolved Configuration

The most powerful debugging tool is

atmos describe stacks

, which shows the final YAML after all imports, merges, and inheritance:

# Describe all components in a stack (most useful for debugging)
atmos describe stacks -s plat-use2-dev

# Describe all stacks (very large output)
atmos describe stacks

# Describe a specific component in a stack
atmos describe component vpc -s plat-use2-dev

The output includes the fully-resolved configuration for each component:

vars - All variables with their final values
settings - Component settings
metadata - Component metadata (type, inheritance chain)
backend - Terraform backend configuration
env - Environment variables

What to Look For

Variable values - Are vars what you expect? Check inheritance from catalog vs stack overrides
Component resolution - Is
```
metadata.component
```
pointing to the right root module?
Backend configuration - Is the S3 bucket/DynamoDB table correct?
Atmos function results - Have
```
!terraform.state
```
expressions resolved?

Filtering with yq

Use

yq

to filter the YAML output and extract specific information:

# Get vars for a specific component
atmos describe stacks -s plat-use2-dev | yq '.components.terraform.vpc.vars'

# Get all component names in a stack
atmos describe stacks -s plat-use2-dev | yq '.components.terraform | keys'

# Check a specific variable across components
atmos describe stacks -s plat-use2-dev | yq '.components.terraform.*.vars.enabled'

# Get backend config for a component
atmos describe stacks -s plat-use2-dev | yq '.components.terraform.vpc.backend'

Disabling Templates and Functions

To debug configuration before template/function processing, disable them:

# See raw config before Go templates are processed
atmos describe stacks -s plat-use2-dev --process-templates=false

# See config before Atmos functions (!terraform.state, etc.) are evaluated
atmos describe stacks -s plat-use2-dev --process-functions=false

# See completely raw config (no templates or functions)
atmos describe stacks -s plat-use2-dev --process-templates=false --process-functions=false

Use cases:

Debugging templates - See the raw
```
{{ }}
```
expressions before evaluation
Debugging functions - See
```
!terraform.state
```
expressions before they resolve
Faster iteration - Skip slow
```
!terraform.state
```
lookups when debugging other issues
No authentication needed - Functions like
```
!terraform.state
```
require AWS access; disable to debug without auth

When to Use Each Command

Command	Use When
`atmos describe stacks -s <stack>`	Debugging a stack - see all components and their resolved config
`atmos describe stacks -s <stack> \| yq '...'`	Extract specific values from a stack
`atmos describe stacks`	Understanding full infrastructure (large output)
`atmos describe component <comp> -s <stack>`	Focused debugging of a single component

Debug Logging

Enable debug logging for detailed Atmos operations:

ATMOS_LOGS_LEVEL=debug atmos terraform plan <component> -s <stack>

Debug output includes:

Stack file loading and import resolution
Variable inheritance chain
Atmos function evaluation (
```
!terraform.state
```
, etc.)
Provider configuration
Backend initialization

Log Levels

```
info
```
(default) - Normal operation
```
debug
```
- Detailed debugging information
```
trace
```
- Maximum verbosity (rarely needed)

Common Issues

Stack Not Found

Error:

stack 'xyz' not found

Debug:

# List available stacks
ls stacks/orgs/acme/

# Check stack file exists
cat stacks/orgs/acme/<tenant>/<stage>/<region>/<layer>.yaml

Common causes:

Typo in stack name
Stack file doesn't exist
Stack name doesn't match naming convention (
```
{tenant}-{region}-{stage}
```
)

Component Not Found

Error:

component 'xyz' not found in stack

Debug:

# Check component exists in filesystem
ls components/terraform/

# Check component is configured in stack
atmos describe stacks -s <stack> | grep -A5 "xyz:"

Common causes:

Component not imported in stack file
Missing catalog import
Component name mismatch between catalog and stack

Atmos Function Errors

Error:

error evaluating !terraform.state: ...

Debug:

# Check the function syntax in your YAML
grep -r "!terraform.state" stacks/catalog/<component>/

# Verify the source component exists and has outputs
atmos describe component <source-component> -s <stack>

# Check if the source component has been deployed
atmos terraform plan <source-component> -s <stack>

Common causes:

Source component not deployed yet (no state)
Wrong output name
Wrong stack name in cross-stack lookups
Circular dependency

For Atmos function syntax and patterns, see the

atmos-functions

skill.

Provider/Authentication Errors

Error:

error configuring provider

AccessDenied

Debug:

# Check authentication is working
atmos auth login --provider acme-sso

# Verify identity resolution
ATMOS_LOGS_LEVEL=debug atmos terraform plan <component> -s <stack> 2>&1 | grep -i identity

For authentication issues, see the

atmos-auth

skill.

Variable Inheritance Issues

Problem: Variable has unexpected value

Debug:

# See the full resolved config
atmos describe component <component> -s <stack>

# Check catalog defaults
cat stacks/catalog/<component>/defaults.yaml

# Check stack overrides
cat stacks/orgs/acme/<tenant>/<stage>/<region>/<layer>.yaml

Inheritance order (later wins):

Component defaults (in Terraform
```
variables.tf
```
)

Catalog defaults (

stacks/catalog/<component>/defaults.yaml

)

Mixin imports (
```
stacks/mixins/
```
)

Stack defaults (

stacks/orgs/acme/<tenant>/<stage>/_defaults.yaml

)

Stack-specific config (

stacks/orgs/acme/<tenant>/<stage>/<region>/<layer>.yaml

)

State/Cache Issues

Problem: Atmos behaving strangely, stale configuration

Fix:

# Clean local Terraform state and cache
atmos terraform clean <component> -s <stack>

# Then re-run
atmos terraform plan <component> -s <stack>

This removes:

```
.terraform/
```
directory
Rendered configuration files
Provider cache

Use when:

Provider versions are out of sync
Module cache is corrupted
Configuration changes aren't being picked up

Validation

Validate all stack configurations before deployment:

atmos validate stacks

This checks:

YAML syntax
Required fields
Schema compliance
Import resolution

Debugging Workflow

Start with describe stacks -
```
atmos describe stacks -s <stack>
```
to see all resolved YAML
Check the basics - Stack exists? Component configured? Imports correct?
Enable debug logging -
```
ATMOS_LOGS_LEVEL=debug
```
for detailed output
Clean and retry -
```
atmos terraform clean
```
to reset state
Check authentication - See
```
atmos-auth
```
skill if AWS errors
Check functions - See
```
atmos-functions
```
skill if
```
!terraform.state
```
errors