DeepSeek Harness Subprocess Exit Codes: 0, 1, 127, 137
An exit code is not an error message; it only says how the process ended. 127 can be a missing command or a wrong PATH; 137 can be an OOM kill or a manual kill (source). Reading the code narrows the search; it does not give the cause.
DeepSeek Harness: Where exit codes come from
The subprocess returns the code; DeepSeek Harness only carries it out. A command calls exit N, the shell returns 127 for a missing command, and the OS returns a signal termination. (source)
Three sources:
- Program exit — the program chooses, such as a failing test returning 1.
- Shell substitution — missing command, non-executable file, missing interpreter.
- Signal termination — the process is killed, and the shell encodes 128+N.
The debugging direction differs: program logic, environment, or resources and cancellation.
DeepSeek Harness adds a tool layer on top. A non-zero code may fail the tool; a zero code with output that violates the schema may also fail the tool. Keep the layers separate.
DeepSeek Harness: Seven common values
Seven values cover most daily work. The table (source):
| Code | Common meaning | Check first |
|---|---|---|
| 0 | Success | Output and side effects |
| 1 | General error | Program log, arguments, business failure |
| 2 | Usage error | Argument format, required fields |
| 126 | Not executable | Permissions, interpreter, noexec mount |
| 127 | Command not found | PATH, install location, spelling |
| 137 | SIGKILL | Memory, OOM, manual kill |
| 143 | SIGTERM | Cancellation, service stop, timeout cleanup |
0 does not guarantee the result is right. A command can succeed with empty output, the wrong directory, or bad data; check output and side effects.
1 and 2 differ: 1 is “the program ran and failed,” 2 is “the program did not start as expected.” One is logic, the other arguments.
126 and 127 differ: 126 is “found but cannot execute,” 127 is “not found.” One is permissions and format, the other PATH and installation.
DeepSeek Harness: Exit codes and signals
128+N is the common shell encoding; N is the signal number. The useful few (source):
- 130 = 128 + 2 — SIGINT, usually Ctrl+C.
- 137 = 128 + 9 — SIGKILL, uncatchable, often a hard kill or OOM.
- 143 = 128 + 15 — SIGTERM, a normal termination request.
This conversion is common on Linux and macOS shells, not universal. Windows uses a different exit-code and signal model; a large integer there is a program or system code, not 128+N.
Signals explain missing cleanup. SIGKILL cannot be caught, so no cleanup runs; SIGTERM can be caught, but the program may ignore it. After 137, do not expect temporary files to be cleaned.
DeepSeek Harness cancellation usually produces a signal-style code depending on the backend. For “cancel left residue,” confirm the signal first, then the cleanup logic.
DeepSeek Harness: What the dsh wrapper changes
DeepSeek Harness keeps the exit code's meaning but adds a tool result. The code travels with the result, along with error codes, output summary, and status. (source)
Three differences:
- Tool failure is not process failure — schema mismatch, spill failure, or oversized output can fail the tool with exit 0.
- Process failure is not always tool failure — some tools treat non-zero as a normal business result.
- Error codes and exit codes are layers — the tool code describes the tool; the exit code describes the process.
That is why “the command works manually but fails in the tool” is common: the command is fine, but an output or permission constraint is not.
glob and grep call bundled binaries through ctx.subprocess, not a shell; they have no shell 127 substitution and report a tool error. Do not apply shell exit-code intuition to every tool.
DeepSeek Harness: Three cases
Three cases cover the common codes. Each gives one smallest action (source):
- 127 command not found — run
command -v <cmd>in the same environment; then check installation, PATH, interpreter, and shebang. - 137 killed — check OOM logs and memory first; if no OOM, look for another process or script sending kill.
- 143 terminated — check whether a user cancelled or a service stopped, whether timeout cleanup sent SIGTERM, and whether the program handled it.
The shared rule is “confirm the source, then the cause.” Do not change code on every non-zero; many are environmental or cancellation.
A zero exit with a wrong result is a different layer. Check output, path, permissions, and schema instead of the code.
DeepSeek Harness: Verify by constructing codes
The best way to learn the mapping is to construct codes. Four experiments (source):
sh -c 'exit 0'— confirm the success path and output.sh -c 'exit 2'— see how a usage error appears.- Run a missing command — see how 127 is shown in the tool.
- Start a long command and cancel — observe 130/143 or the platform equivalent and cleanup.
Four experiments show how the tool wraps codes, what cancellation produces, and whether cleanup runs. That beats guessing in a real failure.
The existing fix-subprocess-byte-truncation-utf8 covers byte truncation, fix-subprocess-scope-unit-leak covers scope leaks, and develop-subprocess-spawn-spec covers the spawn contract; this article covers exit codes and signals. Read the code, then the error code.
FAQ
In DeepSeek Harness, 127 usually means the command was not found or its interpreter path is missing. Check installation, PATH, and the shebang before changing the tool call.
DeepSeek Harness does not work that way. 137 means the process received SIGKILL, often from an OOM kill but also from a manual kill. DeepSeek Harness shows the code; system logs explain the cause.
In DeepSeek Harness, under 128+N, 130 is SIGINT, usually Ctrl+C, and 143 is SIGTERM, usually a termination request. DeepSeek Harness cancellation may produce either depending on the backend.
DeepSeek Harness does not work that way. A DeepSeek Harness tool error describes the tool layer; an exit code describes how the subprocess ended. A successful exit can still fail a tool if output violates its schema.
Related Terms
- exit code
- An exit code is the integer a subprocess returns when it ends; 0 usually means success, and non-zero values classify failures.— DeepSeek Harness reference - Subprocess
- signal
- A signal is an asynchronous OS notification such as SIGINT, SIGTERM, or SIGKILL; shells commonly encode signal termination as 128+N.— DeepSeek Harness reference - Subprocess
- 128+N
- 128+N is the common shell encoding for a process terminated by signal N, such as 128+9=137 for SIGKILL.— DeepSeek Harness reference - Subprocess
- tool error code
- A tool error code is a DeepSeek Harness tool-layer failure identifier, distinct from a subprocess exit code.— DeepSeek Harness reference - Tool schema catalog
Sources
- DeepSeek Harness reference - Subprocess· deepseek-harness
- DeepSeek Harness reference - Tool schema catalog· deepseek-harness