How does Atlas run only one dbt test?

Atlas uses its `bash` tool to execute `dbt test` with the `--select` flag, targeting a specific test by its name or model/column combination, such as `dbt test --select my_model.not_null.my_column`.

Can Atlas trace `ref()` calls in my dbt project?

Yes, Atlas's `lsp` tool understands your dbt model DAG and can perform `goToDefinition` and `findReferences` on `ref()` and `source()` calls to trace data lineage.

How does Atlas add temporary logging to dbt SQL?

Atlas uses its `edit` tool to insert Jinja `{{ log(...) }}` statements directly into your dbt SQL models or macros, providing runtime values for debugging.

Is it safe for Atlas to modify my dbt models?

Yes, Atlas operates with permission-gated tool calls. All proposed changes are presented as a unified diff for your review and approval before being written to disk, ensuring full control.

Will Atlas run `dbt build` against my production environment?

No, Atlas will never run `dbt build` or `dbt run` against a production target without explicit, permission-gated approval, always prompting you if a sensitive target is detected.

How does Atlas ensure my dbt code is formatted after changes?

Atlas can be configured to integrate `sqlfmt` into its workflow. After applying code changes, Atlas can use `sqlfmt` to automatically format your SQL files, maintaining consistent code style.

What dbt files does Atlas interact with during debugging?

Atlas interacts with your `dbt_project.yml`, `packages.yml`, `schema.yml` files, and SQL model files within your `models/` directory, reading configurations and applying code changes.

Can Atlas help with `dbt deps` issues?

While the primary focus is debugging tests, Atlas can use its `bash` tool to run `dbt deps` to resolve package dependencies defined in `packages.yml` if that's part of the problem setup.

Debug a single failing test in dbt with Atlas in 2026

In 2026, dbt developers use Atlas to debug a single failing test by running `dbt test` in isolation, tracing `ref()` and `source()` calls with the `lsp` tool, and applying fixes to the underlying SQL models. Atlas leverages `bash` to execute dbt commands, ensuring the debugging process mirrors manual terminal workflows while providing AI-driven insights and precise code modifications.

How Atlas isolates and runs a single dbt test

Atlas efficiently isolates and runs a single failing dbt test using its `bash` tool, mirroring how a developer would manually execute `dbt test --select` in 2026. This approach ensures that only the relevant test runs, significantly reducing execution time from potentially dozens of minutes to mere seconds, allowing for rapid iteration during debugging.

Atlas integrates directly with your dbt project, allowing it to execute `dbt test` commands just as you would from your terminal. When a specific test fails, Atlas uses its `bash` tool to run `dbt test --select <test_name>` or `dbt test --select <model_name>.<test_type>.<column_name>` to target only the problematic assertion. For instance, if a `not_null` test on the `order_id` column in your `stg_orders` model fails, Atlas might execute `dbt test --select stg_orders.not_null.order_id`. This focused execution minimizes output noise and provides a clear, concise view of the failure, making it easier to diagnose the root cause without sifting through a full suite of passing tests. The `bash` tool also supports additional dbt flags, such as `--vars` for custom variables or `--target` for specific environments, giving Atlas the same flexibility as a human operator.

Tracing dbt model dependencies with Atlas's LSP tool

After identifying a failing dbt test, Atlas uses its `lsp` tool to trace the underlying model dependencies, navigating `ref()` and `source()` calls to understand the data flow. This capability, available in 2026, allows Atlas to quickly jump from a failing schema test in `schema.yml` to the specific SQL model in `models/` that generates the data, providing a comprehensive view of the code path.

Once a dbt test fails, the next step is to understand which part of the dbt model code is responsible. Atlas leverages its `lsp` tool, which understands the structure of your dbt project through AST declarations built with tree-sitter. This allows Atlas to perform operations like `goToDefinition` and `findReferences` on `ref()` and `source()` calls within your SQL files. For example, if a `unique` test fails on a `customer_id` column defined in `models/marts/customers.sql`, Atlas can use `goToDefinition` on `ref('stg_customers')` within that model to navigate directly to `models/staging/stg_customers.sql`. From there, it can trace further back to `source('raw_data', 'customers')` to understand the initial data ingestion. This deep understanding of the dbt model DAG is crucial for pinpointing the exact transformation or source data issue causing the test failure, rather than just the assertion itself.

Forming hypotheses and debugging dbt code with Atlas

Atlas forms hypotheses about dbt test failures and checks them by adding temporary logging or re-running tests with verbose flags, a process refined over 5 years of AI development. Using its `edit` tool, Atlas can insert `{{ log(...) }}` statements directly into your SQL models or Jinja macros, providing runtime insights into intermediate data states without manual file modifications.

With a clear understanding of the dbt model's dependencies, Atlas can formulate a hypothesis about the cause of the test failure. To validate this, Atlas uses its `edit` tool to insert temporary debugging statements. For instance, if a calculation in `models/marts/daily_sales.sql` is suspected, Atlas might add `{{ log("Debug: daily_sales_amount = " ~ daily_sales_amount) }}` to a CTE or a macro. Alternatively, Atlas can re-run `dbt test` with a verbose flag via its `bash` tool, such as `dbt test --select <test_name> --debug`, to get more detailed output from dbt itself. After gathering sufficient information, Atlas will remove any temporary logging using another `edit` operation, ensuring the codebase remains clean. This iterative process of hypothesizing, instrumenting, and observing is fundamental to how Atlas efficiently diagnoses issues in dbt projects.

Applying and reviewing dbt code fixes with Atlas

Atlas applies precise fixes to dbt production code using its `edit` or `apply_patch` tools, ensuring changes are always reviewed and approved by the developer. Every modification, whether to a SQL model in `models/` or a schema definition in `schema.yml`, is presented as a unified diff, allowing for granular control over the 100% AI-generated changes before they are written to disk.

Once the root cause of the dbt test failure is identified, Atlas proceeds to fix the production code. For small, localized changes, Atlas uses its `edit` tool to modify specific lines in files like `models/marts/customers.sql` or `macros/my_macro.sql`. If the fix involves more extensive modifications spanning multiple hunks or files, Atlas can generate a comprehensive patch and apply it using `apply_patch`, which is more robust than chaining multiple `edit` commands. Before any changes are written, Atlas computes a unified diff and surfaces it for your approval. This permission-gated approach, combined with Atlas's ability to snapshot file changes as git patches, ensures that you maintain full control over the codebase. After applying the fix, Atlas will re-run the single failing test with `dbt test --select` and then the full suite with `dbt test` to confirm the resolution and prevent regressions.

Ensuring dbt project integrity and safety with Atlas

Atlas prioritizes the integrity and safety of your dbt project, never running `dbt build` against a production target without explicit permission, a core principle since its 2024 inception. All tool calls are permission-gated, and Atlas drafts a read-only plan before executing any build actions, ensuring your data warehouse remains secure.

Atlas is designed with robust safety mechanisms to protect your dbt project. It operates under strict permission-gated rules, meaning every tool call, including `bash` commands like `dbt build` or `dbt run`, requires explicit approval based on `allow`, `ask`, or `deny` configurations. Crucially, Atlas will never automatically execute `dbt build` or `dbt run` against a production target without your direct consent, always prompting for permission if it detects a sensitive target. Before making any changes or running significant commands, Atlas first drafts a plan in a read-only plan agent, which you can review. Only after your approval does it switch to a build agent to execute the steps. This multi-stage approval process, combined with its ability to read git branches and status, provides a secure and controlled environment for debugging and developing dbt models.

Step by step

01Run the single failing dbt test in isolation: Use Atlas's `bash` tool to execute `dbt test --select <test_name>` or `dbt test --select <model_name>.<test_type>.<column_name>` to focus on the specific failure and minimize output.
02Trace dbt model dependencies: Employ Atlas's `lsp` tool to perform `goToDefinition` and `findReferences` on `ref()` and `source()` calls within the relevant SQL models to understand the data flow leading to the test failure.
03Form a hypothesis and add temporary debugging: Use Atlas's `edit` tool to insert `{{ log(...) }}` statements into your dbt SQL models or macros, or re-run the test with `dbt test --select <test_name> --debug` via `bash` to gather more runtime information.
04Fix the dbt production code: Apply the necessary code changes using Atlas's `edit` tool for small modifications, or `apply_patch` for more extensive fixes across multiple hunks in files like `models/your_model.sql` or `schema.yml`.
05Review and approve changes: Examine the unified diff presented by Atlas for all proposed code edits, ensuring the changes align with your intent before approving them to be written to disk.
06Re-run tests and clean up: First, re-run the single failing test with `dbt test --select` to confirm the fix, then execute the full `dbt test` suite. Finally, use Atlas's `edit` tool to remove any temporary `{{ log(...) }}` statements added during debugging.

Frequently asked questions

How does Atlas run only one dbt test?: Atlas uses its `bash` tool to execute `dbt test` with the `--select` flag, targeting a specific test by its name or model/column combination, such as `dbt test --select my_model.not_null.my_column`.
Can Atlas trace `ref()` calls in my dbt project?: Yes, Atlas's `lsp` tool understands your dbt model DAG and can perform `goToDefinition` and `findReferences` on `ref()` and `source()` calls to trace data lineage.
How does Atlas add temporary logging to dbt SQL?: Atlas uses its `edit` tool to insert Jinja `{{ log(...) }}` statements directly into your dbt SQL models or macros, providing runtime values for debugging.
Is it safe for Atlas to modify my dbt models?: Yes, Atlas operates with permission-gated tool calls. All proposed changes are presented as a unified diff for your review and approval before being written to disk, ensuring full control.
Will Atlas run `dbt build` against my production environment?: No, Atlas will never run `dbt build` or `dbt run` against a production target without explicit, permission-gated approval, always prompting you if a sensitive target is detected.
How does Atlas ensure my dbt code is formatted after changes?: Atlas can be configured to integrate `sqlfmt` into its workflow. After applying code changes, Atlas can use `sqlfmt` to automatically format your SQL files, maintaining consistent code style.
What dbt files does Atlas interact with during debugging?: Atlas interacts with your `dbt_project.yml`, `packages.yml`, `schema.yml` files, and SQL model files within your `models/` directory, reading configurations and applying code changes.
Can Atlas help with `dbt deps` issues?: While the primary focus is debugging tests, Atlas can use its `bash` tool to run `dbt deps` to resolve package dependencies defined in `packages.yml` if that's part of the problem setup.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Debug a Single Failing Test with Atlas in 2026

How to debug one failing test with Atlas in 2026: run it in isolation with bash, walk the call graph with the lsp tool, and fix the code, not the assertion.

Atlas for dbt: Terminal-Native AI Coding in 2026

Atlas is a terminal-native AI coding agent for dbt. Read the ref() DAG, convert a table model to incremental, run dbt build against dev, and add tests in 2026.

Research a Third-Party API Before Integrating it in dbt with Atlas in 2026

Learn how dbt developers use Atlas in 2026 to research external APIs, fetch documentation, and integrate new data sources with confidence, ensuring proper `ref()` calls and schema tests.

Audit a dbt Repository with Parallel Subagents in Atlas in 2026

Sweep your dbt project for issues without context window limits. Atlas uses parallel subagents to audit `dbt_project.yml` and `schema.yml` files, leveraging `dbt test` and `sqlfmt` for comprehensive review.

Diagnose a Hanging or Long-Running dbt Command with Atlas in 2026

Diagnose hanging dbt commands in 2026 with Atlas. Quickly determine if your `dbt build` or `dbt test` is genuinely slow or silently blocked on input, and get it unstuck.

Document a dbt Module with a README in 2026 using Atlas

Atlas helps dbt developers in 2026 generate accurate READMEs for modules by reading live code, ensuring documentation reflects current behavior. It leverages dbt's own toolchain, including dbt test for verification and

Onboard to an Unfamiliar dbt Codebase with Atlas in 2026

Atlas helps dbt developers in 2026 quickly build a mental model of new repositories. Leverage semantic search, `ref()` analysis, `dbt test`, and `sqlfmt` to understand complex dbt projects without reading every file.

Migrate a deprecated API across every callsite in dbt with Atlas in 2026

Migrate deprecated dbt APIs across your entire codebase with Atlas. Find every `ref()` and macro call, validate with `dbt test`, and format with `sqlfmt`.

Browse this resource hub