Diagnose and repair configuration with Atmos Doctor
Configuration can pass schema validation while still using deprecated fields or depending on an archived upstream repository. Migrating those fields also takes care: a valid replacement can change which components run or how missing dependencies behave. The new Atmos Doctor brings those findings together and verifies supported repairs before applying them.
The Problem
Project health checks span configuration schemas, stack validation, formatting, CI workflows, and upstream sources. Deprecation guidance identifies replacement fields, but a replacement is safe only when its behavior matches the original configuration.
The Fix
Doctor combines built-in checks in a streaming report. Supported repairs cover custom-command semantic arguments and flags, recognized legacy hook events, explicit Terraform reconfigure values, simple legacy settings.depends_on lists, and component sources that point at archived repositories. Each repair compares runtime field behavior and unrelated YAML values before writing, and comments on a migrated field move with it. A repair is blocked only by inputs that can change what it means, such as an import, an active profile, or a template in the edited value, and the finding names the file and line responsible. Templates elsewhere in the file do not get in the way. Repaired files can have blank lines or folded scalars reformatted, so review the diff before committing.
A simple dependency list, where each entry names a component and optionally its stack, moves to dependencies.components and adopts modern required semantics on purpose: a missing or disabled target that only produced a warning before is now reported as an error, so you see it before it breaks a deployment. Context selectors, file and folder entries, and stack naming migrations remain manual.
GitHub source metadata identifies archived repositories and distinguishes inaccessible sources from confirmed removal. The health check itself never rewrites source URLs. The one exception is the component-monorepo repair, which moves a source to its successor repository at the same version only after verifying the files are identical. Access errors, private-repository 404 responses, and unsupported hosts remain inconclusive.
How to Use It
Start with a diagnosis, then inspect a verified dry run:
atmos doctor
atmos doctor --fix --dry-run
atmos doctor --fix
The verification and recovery report explains repairs and skipped migrations. Before writing, doctor warns about affected Git changes or unavailable Git and saves exact originals in a private backup directory. Each replacement is atomic; partial failures report exactly which files changed.
For CI, use JSON or SARIF output. Warnings are advisory by default; select --fail-on=warning to make them blocking. Use --offline to skip repository requests; the skipped checks are reported as notices that never trip --fail-on=warning. Doctor exits 2 for invocation errors and when it cannot find a project configuration, and with JSON output those errors arrive in an operational_error field.
Get Involved
Read the command reference and share unsupported migration cases in Atmos discussions.
