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

OSError RuntimeError TimeoutError

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...

Ready to practice your English at work?

Lingua-e has interactive exercises built around real developer conversations: standups, code reviews, retrospectives, and more. Practice until it comes naturally.

Try Lingua-e for free