tox "ERROR: environment failed" in CI

tox built an environment and ran its commands, and something inside returned non-zero. tox reports the failing env and an InvocationError with the exit code, but the real cause is in that env's command output.

What this error means

tox ends with "ERROR: py312: commands failed" or "InvocationError for command ... (exited with code 1)", failing that environment.

python

py312: commands[0]> pytest
...
ERROR: py312: commands failed
ERROR: InvocationError for command /tmp/.tox/py312/bin/pytest (exited with code 1)

Common causes

The wrapped command actually failed

The tests, linter, or build inside the env returned non-zero; tox just surfaces it as an InvocationError.

Env setup or dependency install failed

A dependency in deps failed to install, so the environment could not be created correctly.

How to fix it

Read the failing env output

Find the env that failed (e.g. py312).
Scroll to its command output for the real error.
Fix that command (tests, install, lint) rather than tox itself.

Terminal

tox -e py312 -v

Verify deps and basepython

Ensure the env's deps install and its interpreter is available on the runner.

tox.ini

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

How to prevent it

Keep tox deps in sync with your dev requirements.
Provision every basepython your envs need in CI.
Run tox -e <env> -v locally before pushing.