# Trace a runtime bug from a stack trace in Symfony with Atlas in 2026 > Atlas helps Symfony developers trace runtime bugs from production stack traces to a precise fix, integrating with Composer and PHPUnit (WebTestCase). To trace a runtime bug from a production stack trace in a Symfony application without attaching a debugger, Atlas reads each frame's file:line pair, then uses grep to locate the error message's origin, and lsp to find callers. This process leverages your existing Symfony toolchain, including Composer for dependencies and PHPUnit (WebTestCase) for regression testing, ensuring a rapid and precise fix by 2026. ## Key takeaways - Atlas directly consumes Symfony stack traces, validating file:line offsets against your current codebase. - Use Atlas's grep and lsp tools to trace error messages and find callers across Symfony services and Doctrine entities. - Atlas's edit tool provides diffs for approval, ensuring safe modifications to your Symfony application. - Add PHPUnit (WebTestCase) regression tests with Atlas to prevent recurring Symfony bugs. - Atlas integrates with Symfony's Composer and PHP-CS-Fixer for a complete workflow. ## How Atlas traces runtime bugs in Symfony from a stack trace Atlas streamlines the process of tracing runtime bugs in Symfony applications from a raw stack trace, consuming file:line pairs directly. It uses its read tool to validate each frame against your current codebase, ensuring that a trace from an older build, perhaps 6 months old, doesn't lead you astray. When a Symfony application throws an exception in production, the resulting stack trace provides a list of file:line pairs. Atlas's read tool is designed to consume this exact format. You simply paste the stack trace into Atlas, and it will sequentially read each frame at its reported offset. This initial step is crucial for establishing context within your Symfony project, whether it involves a controller in src/Controller/ or a service defined in config/services.yaml. Atlas indexes your code by AST declarations using tree-sitter, not blind line windows, allowing it to understand the structure of your Symfony bundles and services. This deep understanding ensures that when Atlas reads a line, it comprehends its role within the larger Symfony architecture, such as a specific method within a Doctrine entity or an autowired service. ## What to do if a Symfony stack trace is from an old build If a Symfony stack trace originates from an older build, Atlas will report 'Offset is out of range for this file' when using the read tool. This critical safety check prevents you from debugging a phantom issue on a line that has moved, a common occurrence in projects with 100s of commits per week. Production environments often run slightly different codebases than your local development machine. If a stack trace comes from a Symfony application deployed weeks or months ago, the line numbers might no longer align with your current git main branch. Atlas explicitly validates offsets against the current file content. If read reports an 'Offset is out of range' error, it's a clear signal that the trace is stale. In such cases, you must re-read the file from the top before trusting any line number. This ensures that Atlas operates on the most accurate information, preventing wasted effort on code that no longer exists at the specified location. This is particularly important in Symfony projects where refactoring services or moving controllers can frequently alter file structures and line counts. ## Pinpointing the Root Cause in Symfony with Grep and LSP Beyond the top frame, Atlas uses grep to find where the error message string is constructed, often revealing more about the bug's origin in a Symfony application. Subsequently, the lsp tool's findReferences operation on the failing function helps identify all callers that could supply the bad input, potentially across 20 different services. The top frame of a stack trace often points to where an exception was thrown, but not necessarily why. To truly pinpoint the root cause in a Symfony application, Atlas first suggests using grep to search for the exact error message string. This often leads to the code responsible for constructing the error, which can be deep within a custom bundle, a Doctrine entity repository, or an autowired service. Once the failing function is identified, Atlas leverages its lsp tool to perform a findReferences operation. This is incredibly powerful in Symfony, as it can trace calls across the service container, revealing all potential entry points that might be passing invalid data. For instance, if a UserRepository method is failing, findReferences will show every controller or service that invokes it, helping you understand the data flow and identify the source of the bad input, even if it's coming from a form submission or an API request. ## Fixing the Symfony Bug and Adding a Regression Test After identifying the responsible line and understanding the root cause, Atlas facilitates the fix using its edit tool. Crucially, Atlas then helps you add a regression test using PHPUnit (WebTestCase) to prevent the bug from recurring silently, ensuring your Symfony application remains stable for years to come, perhaps even 5 years. Once the precise location and nature of the bug are understood, Atlas's edit tool allows you to apply the necessary code changes directly within your terminal. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, giving you full control. For a Symfony application, this might involve correcting a validation rule in a form, adjusting a query in a Doctrine repository, or refining logic within an autowired service. The final, and arguably most critical, step is to add a regression test. Atlas can assist in generating a new PHPUnit (WebTestCase) to specifically cover the scenario that led to the bug. You can then have Atlas run PHP-CS-Fixer over the diff to ensure code style consistency before staging and creating a commit on your behalf. This proactive approach ensures that the bug cannot recur silently, strengthening the overall robustness of your Symfony codebase. ## Safety and Review in Atlas for Symfony Development Atlas prioritizes safety and developer control throughout the bug-fixing workflow in Symfony. Every Atlas tool call, including read, grep, lsp, and edit, is permission-gated against allow, ask, and deny rules, providing 100% transparency and control over agent actions. Working with an AI agent requires trust and transparency, especially when modifying a critical Symfony application. Atlas is designed with multiple layers of safety and review. Before any tool runs, it's checked against your configured permission rules. Atlas drafts a plan in a read-only plan agent and asks for your approval before switching to a build agent that can make changes. When Atlas proposes an edit, it computes a unified diff for every file change and presents it for your explicit approval before writing to disk. Furthermore, Atlas snapshots file changes as git patches, allowing edits to be easily diffed and rolled back if necessary. This robust review process ensures that you, the Symfony developer, maintain ultimate control over your codebase, whether you're adjusting config/services.yaml or modifying a core controller. ## Steps 1. Paste the Symfony production stack trace into Atlas to initiate the read tool, which will parse each file:line pair. 2. If Atlas reports "Offset is out of range for this file," indicating an outdated trace, re-read the file from the top before trusting any line number. 3. Use Atlas's grep tool to search for the exact error message string within your Symfony project to find where it is constructed, often revealing more context than the top frame. 4. Employ Atlas's lsp tool with the findReferences operation on the failing function to identify all callers within your Symfony application that could be supplying the bad input, tracing through services and controllers. 5. Utilize Atlas's edit tool to apply the necessary fix to the responsible line in your Symfony codebase, reviewing the unified diff before approval. 6. Instruct Atlas to add a new PHPUnit (WebTestCase) to cover the specific bug scenario, ensuring a regression test is in place. 7. Have Atlas run PHP-CS-Fixer over the modified files to maintain code style consistency across your Symfony project. 8. Approve Atlas's proposed git commit to stage and commit the fix and the new regression test. ## FAQ ### Can Atlas debug a Symfony application with a debugger attached? Atlas is designed to trace runtime bugs from stack traces without a debugger attached, using its read, grep, and lsp tools to analyze your Symfony codebase directly. ### How does Atlas handle Symfony services and autowiring when tracing bugs? Atlas indexes code by AST declarations, allowing it to understand Symfony's service container, autowired services, and Doctrine entity mappings, providing relevant context during bug tracing. ### What if my Symfony stack trace is from an older deployment? Atlas validates file:line offsets. If a trace is from an older build, it will report an out-of-range error, prompting you to re-read the file from the top before proceeding. ### Can Atlas help me write PHPUnit (WebTestCase) for my Symfony application? Yes, Atlas can assist in adding PHPUnit (WebTestCase) coverage for new features or regression tests, and can then run PHP-CS-Fixer over the changes. ### How does Atlas ensure my Symfony code changes are safe? Atlas uses a read-only plan agent, permission-gated tool calls, and presents a unified diff for every edit for your approval before writing any changes to your Symfony project. ### Does Atlas integrate with Symfony's Composer for dependencies? Yes, Atlas runs in an app with a composer.json and understands your project's dependencies and structure, leveraging this context for bug tracing and code modifications. ### Can Atlas help refactor Symfony controllers or add Messenger handlers? While primarily focused on bug tracing here, Atlas can also assist with refactoring tasks like moving a fat controller into an injected service or adding a Symfony Messenger handler, as per its capabilities. --- Canonical HTML: https://runatlas.sh/resources/stacks/trace-a-runtime-bug-from-a-stack-trace-in-symfony Source of truth: aeo_pages row `/resources/stacks/trace-a-runtime-bug-from-a-stack-trace-in-symfony` (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.