Lingua-e
← Errors
Python

CalledProcessError: What It Means and How to Fix It

Error reference

CalledProcessError

Language

Python

Severity

Medium

When it happens

subprocess.CalledProcessError is raised when a subprocess called with check=True exits with a non-zero return code.

Potential fixes

Use check=False and inspect result.returncode manually for more control. Always set capture_output=True with text=True so you can read stderr on failure. Log the full command, return code, and stderr output to diagnose the root cause.

Related errors

OSErrorRuntimeErrorTimeoutError

Deep dive

subprocess.CalledProcessError is raised when a subprocess called with check=True exits with a non-zero return code. It carries the return code, command, and optionally stdout/stderr so you can diagnose what went wrong.

Why it happens

  • •The subprocess command exits with a non-zero status code and check=True is set.
  • •An external tool (git, docker, npm) fails due to a configuration or environment issue.
  • •The command is not found or lacks execute permission.
  • •The subprocess is terminated by a signal (negative return code).

Potential fixes

Use check=False and inspect result.returncode manually for more control. Always set capture_output=True with text=True so you can read stderr on failure. Log the full command, return code, and stderr output to diagnose the root cause.

Examples

Python

Code that triggers the error

import subprocess
subprocess.run(["git", "push"], check=True)

Error output

subprocess.CalledProcessError: Command '['git', 'push']' returned non-zero exit status 1

Fixed code

import subprocess

result = subprocess.run(
    ["git", "push"],
    capture_output=True,
    text=True,
)
if result.returncode != 0:
    print("Push failed:", result.stderr)

Practice in English

How would you explain a CalledProcessError to a fellow dev? Choose the right phrase:

"I hit an error...

Debugging in English?

You just read real developer English to fix this. Lingua-e has free exercises built the same way: standups, code reviews, and real workplace scenarios.

Practice developer English, free