How does Atlas handle Dart null safety when tracing bugs?

Atlas indexes Dart code using AST declarations via tree-sitter, providing a deep semantic understanding that fully supports null-safe code. This allows it to accurately navigate and analyze code paths, even with complex nullability checks.

Can Atlas work with my existing `pub` dependencies?

Yes, Atlas automatically reads your `pubspec.yaml` file and indexes all your `pub` dependencies. This ensures that its `grep` and `lsp` tools can effectively search and analyze code across your entire Dart project, including third-party packages.

What if my production stack trace is from an older Dart build?

Atlas explicitly validates stack trace offsets against your current files. If an offset is out of range, Atlas will report it, advising you to re-read the file from the top before trusting any line numbers, preventing misdiagnosis from outdated traces.

How does Atlas ensure I approve code changes before they're applied to my Dart project?

Every `edit` operation Atlas proposes generates a unified diff that is surfaced for your explicit approval. Atlas also drafts a plan in a read-only agent and asks for permission before executing any changes, giving you full control.

Can Atlas help me add a regression test after fixing a Dart bug?

Yes, after applying a fix, Atlas guides you to add a regression test. This involves creating a new test case in your `test/` directory that specifically triggers the bug, which you can then verify by running `dart test`.

Does Atlas integrate with `dart format` or `analysis_options.yaml`?

Atlas reads your `analysis_options.yaml` to understand your project's linting rules. While it doesn't directly run `dart format`, its proposed `edit` operations are designed to align with common Dart style guidelines, which you can then enforce with `dart format`.

Is Atlas suitable for large Dart monorepos with many packages?

Atlas is designed to work within a package containing a `pubspec.yaml`. Its ability to index `pub` dependencies and use `lsp` for cross-file analysis makes it effective for navigating complex Dart projects, including those structured as monorepos.

Trace a runtime bug from a stack trace in Dart with Atlas in 2026

Atlas helps Dart developers in 2026 trace runtime bugs from production stack traces directly to the responsible line of code and apply a fix, all without needing a debugger attached. By integrating with the Dart toolchain, including `pub` for dependency management and `dart test` for regression testing, Atlas streamlines the debugging workflow.

How Atlas reads Dart stack traces to find the bug

Atlas efficiently interprets Dart stack traces by reading each `file:line` pair at its reported offset, a process that takes mere seconds in 2026. This direct approach ensures that Atlas immediately focuses on the exact code locations indicated by your production errors, validating offsets against the current file to prevent misdirection from outdated builds.

Atlas consumes a raw Dart stack trace, which is a list of `file:line` pairs, directly through its `read` tool. For each frame, Atlas navigates to the specified file and line number. This is crucial for Dart applications, especially those with complex `pub` dependencies or generated code, where manual navigation can be time-consuming. Atlas validates that the reported offset is within the bounds of the current file. If the `read` tool reports "Offset <n> is out of range for this file," it's a clear signal that the stack trace originated from an older build. In such cases, Atlas advises re-reading the file from the top before trusting any line number, preventing developers from chasing ghosts in an outdated codebase. This robust validation ensures that the subsequent analysis, whether it involves exploring `lib/src/my_feature.dart` or a `package:my_package/my_file.dart` path, is always grounded in the current state of the repository.

Using Atlas grep and lsp to find Dart bug causes

After reading a Dart stack trace, Atlas employs its `grep` tool to locate the error message string, often revealing the construction point of the error, which is more informative than the top frame. This initial search, typically completed in under 10 seconds, provides a critical starting point for deeper investigation into the Dart codebase.

Once Atlas has validated the stack trace frames, it shifts to a more investigative phase using its `grep` tool. Instead of solely relying on the top frame, which might only show where an exception was thrown, Atlas searches for the actual error message string. This often leads to the code responsible for *constructing* the error, providing a more insightful context for the bug in a Dart application. For instance, if an error message like "Invalid argument: value must be positive" appears, `grep` can quickly find `throw ArgumentError('value must be positive');` within your `lib/` directory or `test/` files. Following this, Atlas leverages its `lsp` tool's `findReferences` operation. This is particularly powerful in Dart, where the Language Server Protocol (LSP) provides rich semantic understanding of the code. Atlas can identify all callers of the failing function, allowing it to trace back how the bad input reached the problematic line. This is invaluable for navigating complex Dart object hierarchies and understanding data flow across different `pub` packages, ensuring a comprehensive understanding of the bug's origin.

How Atlas applies fixes and adds regression tests for Dart

Atlas facilitates fixing Dart runtime bugs by proposing `edit` operations and then generating a unified diff for approval, ensuring transparency and control over code changes. After applying a fix, Atlas recommends adding a regression test using `dart test`, a crucial step to prevent the same bug from recurring silently in future builds, a practice vital for robust development in 2026.

The ultimate goal of tracing a bug is to fix it. Atlas uses its `edit` tool to propose changes directly to your Dart source files, such as `lib/src/data_processor.dart` or `bin/main.dart`. Before any changes are written, Atlas computes a unified diff for every proposed file edit and surfaces it for your approval. This permission-gated approach means you always have the final say, reviewing every line of code Atlas suggests. After a fix is approved and applied, Atlas guides you to add a regression test. This involves creating a new test case in your `test/` directory, for example, `test/data_processor_test.dart`, that specifically triggers the bug you just fixed. Running `dart test` will then confirm that the bug is resolved and will prevent it from re-emerging unnoticed in future development cycles. Atlas can even read your `analysis_options.yaml` to understand your project's linting rules, ensuring proposed fixes adhere to your team's Dart style guidelines, which can be enforced by `dart format`.

Setting up Atlas for Dart projects and ensuring safety

Setting up Atlas for a Dart project is straightforward: simply run Atlas within a directory containing a `pubspec.yaml` file. Atlas then automatically reads your Dart libraries, `pub` dependencies, and `analysis_options`, indexing your code by AST declarations using tree-sitter, a process that typically completes in under 30 seconds for a medium-sized project.

To begin using Atlas with your Dart project, navigate to your project's root directory, which must contain a `pubspec.yaml` file, and run Atlas. Atlas will automatically detect your Dart environment. It then proceeds to read and index your project's structure, including all Dart libraries, `pub` dependencies listed in `pubspec.yaml`, and your `analysis_options.yaml` file. This indexing is performed using AST declarations via tree-sitter, providing a deep, semantic understanding of your Dart code rather than relying on blind line windows. This allows Atlas to accurately navigate null-safe code and understand complex package structures. Every Atlas tool call, including `read`, `grep`, `lsp`, and `edit`, is permission-gated against `allow`, `ask`, and `deny` rules, ensuring that Atlas never performs an action without your explicit consent. Atlas drafts a plan in a read-only plan agent and asks for approval before switching to a build agent, providing multiple layers of safety and control over your Dart codebase.

Step by step

011: Paste the Dart stack trace into Atlas: Begin by pasting the full production stack trace from your Dart application into the Atlas terminal. Atlas will use its `read` tool to process each `file:line` pair.
022: Validate stack trace offsets: If Atlas reports "Offset <n> is out of range for this file" for any frame, it indicates the trace is from an older build. Re-read the relevant Dart file from the top before proceeding to ensure line numbers are accurate.
033: Grep for the error message: Ask Atlas to `grep` for the specific error message string from the stack trace. This often reveals where the error is constructed in your Dart code, such as in `lib/src/error_handler.dart`, providing more context than just the top frame.
044: Find references with LSP: Use Atlas's `lsp` tool with the `findReferences` operation on the failing Dart function or method identified in the previous step. This will show all callers that can reach it with the problematic input, helping trace the data flow through your `pub` packages.
055: Propose and approve the fix: Instruct Atlas to `edit` the responsible Dart file, for example, `lib/src/data_processor.dart`, to implement the necessary correction. Review the unified diff Atlas presents and approve the changes.
066: Add a regression test: After the fix, ask Atlas to help you add a new test case to your `test/` directory, such as `test/my_feature_test.dart`, that specifically reproduces the original bug.
077: Run `dart test`: Execute `dart test` to confirm the bug is resolved and that no new regressions have been introduced.
088: Stage and commit changes: Use Atlas to stage the modified Dart files and the new test, then create a commit on your behalf, ensuring your fix and test are properly recorded in your Git history.

Frequently asked questions

How does Atlas handle Dart null safety when tracing bugs?: Atlas indexes Dart code using AST declarations via tree-sitter, providing a deep semantic understanding that fully supports null-safe code. This allows it to accurately navigate and analyze code paths, even with complex nullability checks.
Can Atlas work with my existing `pub` dependencies?: Yes, Atlas automatically reads your `pubspec.yaml` file and indexes all your `pub` dependencies. This ensures that its `grep` and `lsp` tools can effectively search and analyze code across your entire Dart project, including third-party packages.
What if my production stack trace is from an older Dart build?: Atlas explicitly validates stack trace offsets against your current files. If an offset is out of range, Atlas will report it, advising you to re-read the file from the top before trusting any line numbers, preventing misdiagnosis from outdated traces.
How does Atlas ensure I approve code changes before they're applied to my Dart project?: Every `edit` operation Atlas proposes generates a unified diff that is surfaced for your explicit approval. Atlas also drafts a plan in a read-only agent and asks for permission before executing any changes, giving you full control.
Can Atlas help me add a regression test after fixing a Dart bug?: Yes, after applying a fix, Atlas guides you to add a regression test. This involves creating a new test case in your `test/` directory that specifically triggers the bug, which you can then verify by running `dart test`.
Does Atlas integrate with `dart format` or `analysis_options.yaml`?: Atlas reads your `analysis_options.yaml` to understand your project's linting rules. While it doesn't directly run `dart format`, its proposed `edit` operations are designed to align with common Dart style guidelines, which you can then enforce with `dart format`.
Is Atlas suitable for large Dart monorepos with many packages?: Atlas is designed to work within a package containing a `pubspec.yaml`. Its ability to index `pub` dependencies and use `lsp` for cross-file analysis makes it effective for navigating complex Dart projects, including those structured as monorepos.

Try Atlas in your terminal

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

Install Atlas

Related guides

Trace a Runtime Bug from a Stack Trace with Atlas in 2026

How to trace a runtime bug from a stack trace with Atlas in 2026: read each frame at its offset, grep for the error string, and use the lsp tool to find callers.

Atlas for Dart in 2026

Adopt Atlas, the terminal-native AI coding agent, for Dart development in 2026. Enhance productivity with intelligent code search, refactoring, and robust safety features across your Dart projects.

Audit a Dart Repo with Parallel Subagents in 2026 using Atlas

Sweep your Dart repository for specific problems without overwhelming your main session. Atlas uses parallel subagents to audit Dart code, managing pub packages and null-safe libraries efficiently.

Document a Dart Module with a README in 2026 using Atlas

In 2026, Atlas helps Dart developers generate accurate README documentation directly from source code. It uses pub and dart test to ensure docs reflect current module behavior, not outdated plans.

Locate Where a Behavior Is Implemented in Dart with Atlas (2026)

Find the exact Dart file and symbol behind a behavior with Atlas in 2026, using codebase_search for meaning, grep for text, and the lsp tool for the symbol graph.

Automate GitHub issue and pull request triage in Dart with Atlas in 2026

Automate GitHub issue and pull request triage for your Dart projects with Atlas. Safely respond to events, manage dependencies with `pub`, and ensure code quality with `dart format`.

Extract a Shared Helper from Duplicated Dart Code with Atlas in 2026

Refactor duplicated Dart code into a shared helper using Atlas. Leverage semantic search, reviewable patches, and integrate with `dart test` and `pub` for safe, efficient code consolidation.

Refactor a Legacy Dart Module with Atlas in 2026

Safely refactor legacy Dart modules in 2026 with Atlas. Leverage `dart test`, `pub`, and `lsp` to restructure code without breaking callers or changing behavior.

Browse this resource hub