{"id":"4178932b9e2d7781","repo":"python-poetry/poetry","slug":"command-e-cmd-errored-with-the-following-return","errorCode":null,"errorMessage":"Command {e.cmd} errored with the following return code {e.returncode}","messagePattern":"Command (.+?) errored with the following return code (.+?)","errorType":"exception","errorClass":"EnvCommandError","httpStatus":null,"severity":"error","filePath":"src/poetry/utils/env/base_env.py","lineNumber":461,"sourceCode":"    def _run(self, cmd: list[str], **kwargs: Any) -> str:\n        \"\"\"\n        Run a command inside the Python environment.\n        \"\"\"\n        call = kwargs.pop(\"call\", False)\n        env = kwargs.pop(\"env\", dict(os.environ))\n        stderr = kwargs.pop(\"stderr\", subprocess.STDOUT)\n\n        try:\n            if call:\n                assert stderr != subprocess.PIPE\n                subprocess.check_call(cmd, stderr=stderr, env=env, **kwargs)\n                output = \"\"\n            else:\n                output = subprocess.check_output(\n                    cmd, stderr=stderr, env=env, text=True, encoding=\"locale\", **kwargs\n                )\n        except CalledProcessError as e:\n            raise EnvCommandError(e)\n\n        return output\n\n    def execute(self, bin: str, *args: str, **kwargs: Any) -> int:\n        command = self.get_command_from_bin(bin) + list(args)\n        env = kwargs.pop(\"env\", dict(os.environ))\n\n        if not self._is_windows:\n            return os.execvpe(command[0], command, env=env)\n\n        kwargs[\"shell\"] = True\n        exe = subprocess.Popen(command, env=env, **kwargs)\n        exe.communicate()\n        return exe.returncode\n\n    @abstractmethod\n    def is_venv(self) -> bool: ...\n","sourceCodeStart":443,"sourceCodeEnd":479,"githubUrl":"https://github.com/python-poetry/poetry/blob/92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54/src/poetry/utils/env/base_env.py#L443-L479","documentation":"Raised as EnvCommandError inside base_env._run when a subprocess invocation (subprocess.check_call / check_output) launched within the managed virtualenv exits with a non-zero return code (subprocess.CalledProcessError). It wraps the failing command, its return code, and any captured stdout/stderr so the caller can see why the in-env command failed. It is the generic failure mode for every shell command Poetry runs inside an environment (pip installs, python -c probes, etc.).","triggerScenarios":"Calling Env._run (directly or via methods that delegate to it, e.g. run_pip / run_python_script) with a command whose executable is missing inside the venv, whose arguments are invalid, or which itself exits non-zero (a pip install resolving a broken wheel, a build script that fails, a python -c that raises). Any path in base_env.py:443-461 that hits the CalledProcessError branch.","commonSituations":"A dependency fails to build its wheel under the current platform/Python; the venv's python or pip binary is corrupted/removed; network or index misconfiguration causes pip to abort; a post-install hook script errors. Also seen after manually deleting packages out from under the venv.","solutions":["Read the appended 'Output:' / 'Error output:' section of the exception message - it carries the real underlying error from the subprocess.","Reproduce the failing command manually inside the venv (source the venv, run the exact cmd from e.cmd) to iterate faster.","Fix the root cause surfaced by the output (install build deps, fix network/proxy, correct package version) and re-run.","If the venv is corrupted, recreate it: 'poetry env remove <env>' then 'poetry install'."],"exampleFix":"// before\nenv.run_pip(\"install\", \"some-broken-pkg==9.9.9\")  # EnvCommandError\n\n// after - inspect output, pin a buildable version\nenv.run_pip(\"install\", \"some-broken-pkg==1.2.3\")","handlingStrategy":"try-catch","validationCode":"import shutil, subprocess\n\ndef env_can_run(env, cmd: list[str]) -> bool:\n    exe = cmd[0]\n    return shutil.which(exe, path=env.path.as_posix()) is not None\n\n# before calling env._run / run_pip:\nassert env_can_run(env, [\"pip\"]), \"pip missing in env\"","typeGuard":"from subprocess import CalledProcessError\n\ndef is_env_command_error(e: Exception) -> bool:\n    # EnvCommandError wraps a CalledProcessError on attribute .e\n    return isinstance(e, Exception) and getattr(e, \"e\", None) is not None and isinstance(getattr(e, \"e\"), CalledProcessError)","tryCatchPattern":"from poetry.utils.env.exceptions import EnvCommandError, EnvError\n\ntry:\n    env.run_pip(\"install\", pkg)\nexcept EnvCommandError as e:\n    # e.e is the original CalledProcessError; e.e.output / e.e.stderr hold detail\n    log.error(\"pip failed (rc=%s): %s\", e.e.returncode, (e.e.stderr or b\"\").decode())\n    raise\nexcept EnvError:\n    raise","preventionTips":["Always inspect e.e.output and e.e.stderr - the real cause is the wrapped subprocess output.","Pin reproducible dependency versions so pip resolution does not fail unpredictably.","Run long pip installs with a timeout and a local wheelhouse/cache to avoid transient network failures.","Recreate the venv if multiple unrelated commands start failing - it is likely corrupted."],"tags":["subprocess","virtualenv","env-command","pip"],"analyzedSha":"92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54","analyzedAt":"2026-08-04T20:33:34.072Z","schemaVersion":2}