# Trace a runtime bug from a stack trace in dbt with Atlas in 2026 > Atlas helps dbt developers in 2026 quickly trace runtime bugs from stack traces to a fix, integrating with `dbt test` and `sqlfmt`. In 2026, dbt developers can trace a runtime bug from a production stack trace to the responsible line and apply a fix without attaching a debugger, using Atlas. Atlas leverages its `read`, `grep`, `lsp`, and `edit` tools to navigate dbt projects, identify issues in `ref()` calls or materialization strategies, and propose fixes, which are then validated with `dbt test` and formatted with `sqlfmt`. ## Key takeaways - Atlas directly consumes dbt stack traces, validating file offsets for accuracy. - `grep` and `lsp` tools quickly pinpoint root causes in dbt `ref()` calls and `schema.yml` tests. - Atlas `edit` tool facilitates precise fixes for dbt models and configurations. - Regression tests, like `not_null` and `unique` in `schema.yml`, are integrated into the fix workflow. - Atlas ensures dbt code quality by integrating `sqlfmt` into the resolution process. - All Atlas actions on your dbt project are permission-gated and auditable via diffs and git patches. ## How Atlas Reads dbt Stack Traces When a dbt model fails in production, Atlas can immediately begin tracing the runtime bug from its stack trace. The Atlas `read` tool consumes the file:line pairs from the trace, validating each offset against the current file to ensure the trace isn't from an older build, preventing misdiagnosis in 2026. A dbt stack trace provides critical file and line number information, which Atlas's `read` tool processes directly. For instance, if a trace points to `models/marts/my_model.sql` at line 42, Atlas will read that specific line and its surrounding context. This is crucial in dbt projects where `ref()` and `source()` calls define complex data dependencies. Atlas ensures the reported offset is valid for the current version of the file. If the `read` tool reports "Offset is out of range for this file," it signals that the stack trace originated from a different build, prompting Atlas to re-read the file from the top before trusting any line number. This prevents misinterpreting an outdated trace and ensures that the debugging process targets the correct code in your `dbt_project.yml` defined models. ## Pinpointing dbt Error Origins with Grep and LSP After reading the initial stack trace, Atlas uses its `grep` and `lsp` tools to pinpoint the exact origin of a dbt runtime error. Grepping for the specific error message string often reveals where the error is constructed, which is typically more informative than just the top frame, providing a 10x faster path to resolution. To move beyond the immediate failure point, Atlas first employs its `grep` tool to search for the exact error message string across your dbt project. This often uncovers the underlying logic that generates the error, which might be in a macro, a custom materialization, or a complex `ref()` call within a `models/` file. Once a potential failing function or expression is identified, Atlas leverages its `lsp` tool's `findReferences` operation. This allows Atlas to trace all callers that can reach the failing function with the problematic input. For example, if a `schema.yml` test like `not_null` or `unique` is failing due to bad data, Atlas can trace back through `ref()` calls to identify the upstream model or source responsible for introducing the invalid data, even across multiple layers of your dbt DAG. This comprehensive approach ensures that the fix addresses the root cause, not just the symptom. ## Applying and Validating dbt Fixes Once the root cause of a dbt bug is identified, Atlas facilitates the fix using its `edit` tool and ensures future stability by adding regression tests. Atlas can propose changes to `models/` files, `schema.yml` tests, or even `dbt_project.yml` configurations, aiming for a 100% reduction in recurrence for that specific issue. Atlas's `edit` tool allows for precise modifications to your dbt codebase. For instance, if a model is failing due to an incorrect `is_incremental()` filter or a missing `unique_key` in an incremental materialization, Atlas can draft the necessary SQL changes. After applying the fix, Atlas's workflow mandates adding a regression test. This might involve adding a new `not_null` or `unique` test to `schema.yml` for a newly identified data quality issue, or modifying an existing `dbt test` to specifically catch the previously observed bug. Atlas can then run `dbt build` against your dev target (behind a permission prompt) to validate the fix and ensure no new issues are introduced. Finally, Atlas can invoke `sqlfmt` to ensure the modified SQL adheres to your project's formatting standards, maintaining code quality across your dbt project. ## Secure and Auditable dbt Bug Resolution with Atlas Atlas provides a secure and auditable workflow for resolving dbt bugs, ensuring every change is transparent and approved. Every Atlas tool call, including `read`, `grep`, `lsp`, and `edit`, is permission-gated, and all proposed edits are presented as unified diffs for user approval, offering 100% control over your dbt project. Atlas is designed with robust safety mechanisms crucial for production dbt environments. Before any tool call, such as running `dbt build` or modifying a `models/` file, Atlas consults permission-gated allow, ask, and deny rules. This ensures that sensitive operations are never performed without explicit consent. Atlas first drafts a plan in a read-only plan agent, asking for approval before switching to a build agent that can make changes. For every proposed file edit, Atlas computes a unified diff and surfaces it for your review and approval before writing to disk. This allows dbt developers to meticulously inspect changes to `dbt_project.yml`, `schema.yml`, or SQL models. Furthermore, Atlas reads git branches, status, and diffs, and can stage and create commits on your behalf, even snapshotting file changes as git patches for easy diffing and rollback, providing a complete audit trail for every bug fix. ## Steps 1. Paste the dbt stack trace into Atlas: Begin by pasting the full production stack trace from your dbt runtime error directly into the Atlas terminal. 2. Have Atlas `read` each frame: Atlas will use its `read` tool to examine each `file:line` pair from the trace, specifically checking dbt model files in your `models/` directory. 3. Validate trace offsets and re-read if necessary: If Atlas reports "Offset is out of range for this file," indicating an outdated trace, instruct Atlas to re-read the file from the top before proceeding. 4. Grep for the dbt error message: Ask Atlas to `grep` for the specific error message string to find where it's constructed, often revealing the underlying issue in a dbt macro or `ref()` call. 5. Use `lsp` to find references to the failing dbt function: Employ Atlas's `lsp` tool with `findReferences` on the identified failing function or expression to trace all callers that can supply the bad input, potentially upstream in your dbt DAG. 6. Edit the dbt code to apply the fix: Use Atlas's `edit` tool to modify the responsible line, perhaps adjusting a `materialization` strategy, an `is_incremental()` filter, or a `unique_key` definition. 7. Add a dbt regression test: Instruct Atlas to add a new `not_null` or `unique` test to your `schema.yml` or modify an existing `dbt test` to prevent the bug from recurring silently. 8. Run `dbt build` and `sqlfmt`: Validate the fix by having Atlas run `dbt build` against your dev target (with permission), then ensure code quality by running `sqlfmt` on the modified SQL files. ## FAQ ### How does Atlas handle dbt stack traces from different environments? Atlas validates each file:line offset from a dbt stack trace against the current project files. If an offset is out of range, Atlas flags it, indicating the trace is from a different build, and prompts to re-read the file from the top for accurate context. ### Can Atlas debug issues within dbt macros or custom materializations? Yes, Atlas uses its `grep` tool to search for error messages within your entire dbt project, including macros and custom materializations. Its `lsp` tool can then trace `findReferences` to pinpoint the exact call site causing the issue. ### How does Atlas ensure I don't accidentally deploy a bad fix to dbt production? Atlas operates with permission-gated tool calls, drafts plans in a read-only agent, and presents all proposed `edit` changes as unified diffs for your explicit approval before writing. It also connects to git for staging and committing. ### What dbt-specific files and commands does Atlas interact with? Atlas interacts with `dbt_project.yml`, `models/` directories, `schema.yml` files, and understands `ref()` and `source()` calls. It uses actual commands like `dbt test`, `dbt build`, `dbt deps (packages.yml)`, and `sqlfmt`. ### How does Atlas help add regression tests for dbt bugs? After an `edit` fix, Atlas can be instructed to add specific regression tests, such as new `not_null` or `unique` tests to `schema.yml` for data quality issues, or modify existing `dbt test` definitions to prevent recurrence. ### Can Atlas help optimize dbt models during bug fixing? While primarily focused on bug tracing, Atlas can assist with optimization by, for example, converting an expensive table model to incremental with a proper `is_incremental()` filter and `unique_key` as part of a fix, if relevant to the bug. ### Does Atlas integrate with dbt's package management? Atlas understands the dbt toolchain, including `dbt deps (packages.yml)`. While not directly managing packages, it can navigate and understand code within installed packages when tracing issues. --- Canonical HTML: https://runatlas.sh/resources/stacks/trace-a-runtime-bug-from-a-stack-trace-in-dbt Source of truth: aeo_pages row `/resources/stacks/trace-a-runtime-bug-from-a-stack-trace-in-dbt` (segment: Stacks) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.