Process exited with code 1 - A practical debugging guide

TL;DR: Code 1 is a generic failure. Surface the real error by capturing stderr, enable verbose logs, minimize to a small repro, and handle non-zero exits deliberately. Treat the exit code as a symptom, not the bug.

What exit codes mean

Programs return 0 for success and non-zero for failures. Code 1 is a conventional generic failure. The fix is inside logs and the stack trace, not in the number 1 itself.

Surface the real error

# Bash: capture output
mycmd 1>out.log 2>err.log || echo "failed with $?. see err.log"

// Node: log errors
child_process.exec("mycmd", (err, stdout, stderr) => {
  if (err) {
    console.error(stderr);
    process.exitCode = err.code || 1;
  }
});

Common causes by stack

• Node - missing env vars, network failures, unhandled promise rejections.
• Python - ImportError, invalid CLI args, unhandled exceptions.
• CI/CD - failing tests, missing artifacts, wrong paths.

Defensive scripting

set -euo pipefail
trap 'echo "Error on line $LINENO"' ERR

Checklists

• Run the command locally with the same env as CI.
• Add verbose flags or debug logs.
• Validate inputs and file paths.
• Return meaningful codes from your program.

FAQ

How is code 1 different from other codes
It is generic. Your program can define specific codes for common failures like 2 for usage errors.

How do I make scripts fail fast but readable
Use shell options, traps, and clear echo statements that explain what the script was doing when it failed.

Cast this in your project

• Process Exited with Code 1 T-shirt for logs and coffee days.
• You Can't Scare Me T-shirt for production firefighters.

Image credit: Photo by monicore: https://www.pexels.com/photo/green-and-white-male-gender-rest-room-signage-134065/