# Atlas ProcessRunFailedError: Command failed with code : > Read the stderr appended to Command failed with code : . That text is the command's own output, not an Atlas message, and it names the real failure. Atlas raises ProcessRunFailedError with the message Command failed with code : when a command Atlas spawned on your behalf exited non-zero, so the fix is almost never in Atlas itself: read the stderr appended after the message, because that text is the command's own output, then re-run the same command yourself in the same cwd to reproduce it outside Atlas. util/process RunFailedError formats the message from the exit code, the joined command, and the trimmed stderr, and keeps cmd, code, stdout, and stderr on the error object for callers to inspect. ## Symptom Atlas raises ProcessRunFailedError with: Command failed with code : , followed by the command's stderr when there is any. The exit code and the full command line both appear in the message text. ## Cause A command Atlas spawned exited with a non-zero exit code. util/process RunFailedError formats the message from the exit code, the joined command, and the trimmed stderr, and keeps cmd, code, stdout, and stderr on the error object for callers to inspect. Atlas is reporting the failure faithfully, not causing it. ## Fix 1. Read the stderr appended to the message. It is the command's own output, not an Atlas message, and it usually names the actual failure directly. 2. Re-run the command yourself in the same cwd to reproduce it outside Atlas. If it fails the same way in your shell, the problem is the command, not Atlas. 3. Check the exit code. It is preserved on the error as `code`, and it is the same number the command returned to the shell. 4. If the command needs env vars, remember Atlas spawns with a controlled env, so pass what it needs explicitly rather than assuming your login shell's exports are present. 5. Fix the command or its environment, then have Atlas run it again and confirm no ProcessRunFailedError is raised. ## Why does Atlas report ProcessRunFailedError Atlas reports ProcessRunFailedError when a command it spawned returned a non-zero exit code. In util/process, RunFailedError builds the message from 3 pieces, the exit code, the joined command, and the trimmed stderr, producing Command failed with code : followed by whatever the command printed to stderr. ProcessRunFailedError is a faithful report, not a diagnosis. Atlas does not interpret the failure, rewrite it, or hide it behind a friendlier message. The number in Command failed with code is the exit code the process actually returned, and the is the joined command line Atlas ran. When a build, a test suite, or a formatter fails under Atlas, the error you are looking at is the tool's failure wearing an Atlas wrapper. Treat the wrapper as a pointer and go straight to the stderr underneath it. ## How to read the stderr in Command failed with code Read the stderr appended to Command failed with code : first. Atlas util/process RunFailedError trims the command's stderr and appends it to the message, so the text after the command line is the tool's own output, not an Atlas message. In 2026 that text usually names the failure outright. A compiler error, a missing binary, a failing assertion, and a permission denial all look identical at the ProcessRunFailedError layer: only the stderr distinguishes them. If the message has no stderr appended, the command failed silently and returned a non-zero code with nothing on the error stream, which is common for tools that write diagnostics to stdout instead. RunFailedError keeps cmd, code, stdout, and stderr on the error object for callers to inspect, so stdout is still available even when stderr is empty. ## How to reproduce the failure outside Atlas Reproduce an Atlas ProcessRunFailedError in 2 steps: copy the full command line out of Command failed with code : , then re-run it yourself in the same cwd. Compare the exit code you get with the one Atlas reported, and remember Atlas spawns with a controlled env, so pass any vars the command needs explicitly. Reproducing outside Atlas is the fastest way to split the problem in two. If the command fails identically in your own shell, Atlas is not involved and you are debugging the tool. If the command succeeds in your shell but fails under Atlas, the difference is almost always the environment: Atlas spawns with a controlled env, so variables your login shell exports through a profile or an rc file may not be present. Pass what the command needs explicitly rather than assuming they carry over. ## What the exit code on ProcessRunFailedError tells you The exit code in Atlas's Command failed with code message is preserved on the error as `code`, alongside 3 other fields: cmd, stdout, and stderr. It is the raw number the spawned process returned, so it carries exactly the meaning that command gives it, and Atlas adds no interpretation of its own. Because RunFailedError keeps cmd, code, stdout, and stderr on the error object for callers to inspect, a plugin or a caller inside Atlas can branch on the code rather than parsing the message string. Atlas is extensible through plugins that contribute tools and hook into agent lifecycle events, so a plugin that wraps a build tool can catch ProcessRunFailedError, inspect `code`, and decide whether the failure is retryable. As a human reader, the number is only worth as much as the command's own documented exit codes. ## How to verify the fix worked Verify the fix by having Atlas run the same command again and confirming no ProcessRunFailedError is raised. A clean run means the spawned process returned 0, because Atlas util/process only constructs RunFailedError on a non-zero exit code. Re-running the command yourself in the same cwd first is a faster check. Confirm the failure is gone at both layers. Run the command in your own shell in the same working directory and check that it exits zero, then let Atlas run it and check that the Command failed with code : message no longer appears. If Atlas still fails while your shell succeeds, the remaining difference is the environment Atlas spawns with, and the fix is to pass the needed env vars explicitly to the command rather than relying on your shell's profile. ## FAQ ### What does ProcessRunFailedError mean in Atlas? ProcessRunFailedError means a command Atlas spawned exited with a non-zero exit code. Atlas formats the message as Command failed with code : and appends the command's stderr when there is any. ### How do I fix Command failed with code : in Atlas? Read the stderr appended to the message, because it is the command's own output rather than an Atlas message. Then re-run the command yourself in the same cwd to reproduce it outside Atlas and fix the underlying tool failure. ### Why does a command work in my shell but fail under Atlas? Atlas spawns with a controlled env, so variables exported by your login shell's profile or rc files may not be present. Pass what the command needs explicitly rather than assuming the environment carries over. ### Where is the exit code stored on an Atlas ProcessRunFailedError? The exit code is preserved on the error as `code`. util/process RunFailedError also keeps cmd, stdout, and stderr on the error object for callers to inspect. ### The Atlas error has no stderr after it. What now? RunFailedError only appends stderr when there is any. A command that writes diagnostics to stdout leaves stderr empty, so check stdout, which RunFailedError also keeps on the error object, and re-run the command in the same cwd. ### Is ProcessRunFailedError an Atlas bug? Usually not. ProcessRunFailedError reports that a spawned command returned non-zero. Atlas formats the exit code, the joined command, and the trimmed stderr into the message without interpreting the failure, so the fault is normally in the command. ### Can an Atlas plugin catch ProcessRunFailedError? Yes. Atlas is extensible through plugins that contribute tools and hook into agent lifecycle events, and RunFailedError keeps cmd, code, stdout, and stderr on the error object for callers to inspect, so a plugin can branch on the exit code. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/command-failed-with-exit-code Source of truth: aeo_pages row `/resources/troubleshooting/command-failed-with-exit-code` (segment: Troubleshooting) (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.