tox "ERROR: InvocationError ... (exited with code N)" in CI

tox runs the commands in an environment and reports InvocationError when one exits non-zero. tox itself is fine; the wrapped command (pytest, flake8, a script) failed, and its exit code tells you which.

What this error means

tox ends with ERROR: InvocationError for command <cmd> (exited with code N) and the env marked failed. The real failure is in the command’s own output above; the exit code maps to that tool’s meaning (e.g. pytest 1 = failures, 5 = no tests).

tox output

py311: commands[0]> pytest
...
ERROR: InvocationError for command /repo/.tox/py311/bin/pytest
(exited with code 1)
py311: FAIL code 1 (12.30 seconds)

Common causes

A wrapped command failed

pytest had failures, a linter found violations, or a script errored. tox surfaces it as InvocationError with that command’s exit code.

Missing dependency or wrong command in the env

The tox env did not install a needed dependency, or commands/deps are misconfigured, so the command exits non-zero (e.g. 127 not found).

How to fix it

Read the failing command and its exit code

Identify which commands[N] failed and the exit code in the InvocationError.
Map the code to that tool (pytest 1=failures, 5=no tests; flake8 1=violations; 127=command not found).
Fix the underlying tool failure, not tox.

Fix env deps and reproduce in isolation

Add missing deps to the env and run just that env to debug.

tox.ini

# tox.ini
[testenv]
deps =
    pytest
    -r requirements-dev.txt
commands = pytest

# run one env, recreating it cleanly
tox -e py311 -r

How to prevent it

Declare every tool the env runs in deps.
Map exit codes to the failing tool instead of treating all failures alike.
Use tox -e <env> -r to reproduce a single env cleanly.