Atlas raises ProcessRunFailedError with the message Command failed with code <n>: <cmd> 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.
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 <n>: <cmd> 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 <n> is the exit code the process actually returned, and the <cmd> 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 <n>
Read the stderr appended to Command failed with code <n>: <cmd> 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 <n>: <cmd>, 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 <n> 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 <n>: <cmd> 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.
How to fix it
- 01Read 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.
- 02Re-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.
- 03Check the exit code. It is preserved on the error as `code`, and it is the same number the command returned to the shell.
- 04If 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.
- 05Fix the command or its environment, then have Atlas run it again and confirm no ProcessRunFailedError is raised.
Frequently asked questions
- 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 <n>: <cmd> and appends the command's stderr when there is any.
- How do I fix Command failed with code <n>: <cmd> 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.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas with AllenAI Olmo 3 32B Think: the fully open reasoning model in 2026
Run Atlas on AllenAI Olmo 3 32B Think in 2026: 65,536 token context, OpenRouter $0.15/$0.50 per Mtok, and the only weights, data, and training code you can audit.
Atlas with Kimi K2 Turbo: Pricing, Context, and Setup in 2026
Kimi K2 Turbo in Atlas costs $2.40 per Mtok input and $10.00 per Mtok output on a 256K tokens (262,144) window. A latency purchase, not a capability upgrade.
Atlas with Hugging Face Inference in 2026: 51 Models Behind One HF_TOKEN
Atlas with Hugging Face Inference in 2026: 51 routed models behind one HF_TOKEN, GLM-4.7-Flash free at $0/$0 per Mtok, and the router margin on popular rows.
Atlas for Electron: Terminal-Native AI Coding for Main, Preload, and Renderer in 2026
Atlas is a terminal-native AI coding agent for Electron in 2026, where the main and renderer split, contextIsolation, and preload bridges are the security model.
Atlas with GPT-5.2: The 400K General Purpose GPT in 2026
GPT-5.2 runs Atlas on a 400K context with 128K max output at $1.75 per Mtok input, $14 per Mtok output. Setup, the price rise from GPT-5.1, and the Codex tradeoff.
Atlas vs Pieces for Developers: AI Tools for Developers in 2026
Comparing Atlas, a terminal-native AI coding agent, with Pieces for Developers, an OS-level memory layer, for developers in 2026. Evaluate code generation, safety, and context management.
Atlas with North Mini Code in 2026: A 64,000 Token Output Budget
North Mini Code gives Atlas a 256,000 token context and a 64,000 token output, 8x Command A's 8,000, listed at $0 per Mtok on both input and output in the registry.
Upgrade a Dependency and Fix the Breakage with Atlas (2026 Workflow)
How to upgrade a dependency and fix the breakage with Atlas in 2026: bash drives the package manager, webfetch pulls the release notes, edit fixes each compiler error.