Skip to main content

Breaking Change: Empty base_path No Longer Defaults to Current Directory

· 3 min read
Andriy Knysh
Andriy Knysh
Principal Architect @ Cloud Posse

Starting with Atmos v1.202.0, empty or omitted base_path values in atmos.yaml now trigger git root discovery instead of defaulting to the current directory. Users with multiple Atmos projects in a single repository, or where the Atmos project root differs from the git root, must explicitly set base_path: ".".

What Changed​

The interpretation of base_path in atmos.yaml has changed:

Before (v1.201.x and earlier):

# Both treated as "current directory"
base_path: ""
base_path: "."

After (v1.202.0+):

# Triggers git root discovery with fallback
base_path: ""

# Explicitly uses config file directory relative to the location of the `atmos.yaml`
base_path: "."

These are no longer equivalent. An empty base_path now means "find the git repository root and use that", while "." explicitly means "use the directory where atmos.yaml is located".

Who Is Affected​

You may be affected if:

  1. Multiple Atmos projects in one repository - Each project has its own atmos.yaml in a subdirectory
  2. Atmos project root differs from git root - Your atmos.yaml is not at the repository root
  3. Using refarch-scaffold or similar patterns - Where atmos.yaml is in a nested directory

Symptoms​

If affected, you'll see errors like:

The atmos.yaml CLI config file specifies the directory for Atmos stacks
as stacks, but the directory does not exist.

Or:

atmos exited with code 1

How to Fix​

Update your atmos.yaml to explicitly specify the base path:

# Before (no longer works as expected)
base_path: ""

# After (explicit current directory)
base_path: "."

Option 2: Use Relative Paths​

If your stacks and components are relative to the config file:

base_path: "."

stacks:
  base_path: "stacks"

components:
  terraform:
    base_path: "components/terraform"

Option 3: Navigate to Project Root​

If you prefer empty base_path, ensure you run Atmos from the git repository root where stacks/ and components/ directories exist.

Path Resolution Semantics​

For reference, here's how different base_path values are now interpreted:

base_path valueResolves toUse case
"" (empty/unset)Git repo root, fallback to config dirDefault - single project at repo root
"."Directory containing atmos.yamlExplicit config-relative paths
".."Parent of config directoryConfig in subdirectory
"./foo"config-dir/fooExplicit relative path
"foo"git-root/foo with fallbackSimple relative path
"/absolute/path"As specifiedAbsolute path override

Why This Change?​

This change was made to support running atmos commands from anywhere within a repository, similar to how git commands work. The git root discovery enables:

  • Running atmos terraform plan vpc -s dev from any subdirectory
  • Consistent behavior regardless of current working directory
  • Better alignment with developer workflows

For users with non-standard project layouts, the explicit base_path: "." provides the previous behavior.

References​