What the agent does
The error comes from pip, but the cause is the base image. Debian 12 and Ubuntu from 23.04 on ship a marker file named EXTERNALLY-MANAGED next to the system Python, and pip refuses to install into an interpreter that has one. A Dockerfile that never changed starts failing the day its base tag moves to such a release. The agent reads the Dockerfile for exactly that pattern. In github/ghas-jira-integration it is the first three lines: FROM ubuntu:latest, then apt-get install -y python3 python3-pip, then RUN pip3 install pipenv. The tag is a moving one, the Python is the distribution's, and the third line installs into it as root.
The sandbox has no Docker, so the agent installs it first (sudo apt-get install -y docker.io, then starts dockerd), runs docker build . on the untouched file and keeps the failing step's output. Then it reads what the image is for before choosing a fix. Here entrypoint.sh runs pipenv run /gh2jira sync with a list of INPUT_ variables, and a later line of the Dockerfile runs PIPENV_VENV_IN_PROJECT=1 pipenv install. That detail matters: pipenv builds its own virtual environment for the project's packages, so those never touch the system Python. Only the installation of pipenv itself trips the check. The fix is one tool, not the whole dependency set.
With that known, the agent lists the options and what each costs in this file. Installing pipenv from the distribution (apt-get install -y pipenv) keeps the system Python managed by apt, at the price of whatever version the release carries. A small virtual environment for tools (python3 -m venv, which needs the python3-venv package, with its bin directory put on PATH) keeps the current pipenv from PyPI. Switching the base to an official python: image removes the problem at its source, because that image builds Python under /usr/local with no marker file, and it also fixes which Python version the tool runs on. pip3 install --break-system-packages, or PIP_BREAK_SYSTEM_PACKAGES=1, is the one-line change most search results suggest; the agent names it and explains why it is last on the list: the flag turns the check off for that call, the variable for every later pip call in the image, and neither stops pip from overwriting a module that apt installed.
It applies the smallest option that builds, and it pins the base tag to a named release, since latest is how the image broke without a commit. Then it rebuilds and starts the container far enough to prove the entrypoint's tool chain works, running pipenv run /gh2jira --help inside it. It reports two things it found and did not fix. The repository has a Pipfile but no Pipfile.lock, so every build resolves flask, requests and jira afresh. And no workflow builds this Dockerfile: .github/workflows/python.yml only runs black and flake8, which is why the break went unnoticed.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "The Docker build for this repository fails with \"error: externally-managed-environment\" from pip. There is no Docker in your sandbox: install it with `sudo apt-get install -y docker.io` and start dockerd first. Build every Dockerfile in the repository unchanged and save the output of the failing step. For each failing pip command, say which interpreter it installs into, which base image and tag provide it, and whether that tag is a moving one such as latest. Read the entrypoint and the rest of the Dockerfile to see what the installed packages are used for, and whether a later step already creates a virtual environment. List the possible fixes for this file with their trade-offs: the distribution's own package, a virtual environment on PATH, pipx, an official python base image, and --break-system-packages. Apply the least invasive one that is not the override flag; use the flag only if nothing else builds, and say why. Pin the base image to a named release instead of a moving tag. Rebuild, then run the container's entrypoint tool with --help or its equivalent to prove the installed packages import. Do not change application code or dependency versions. Report, without fixing, a missing lock file and whether any CI workflow builds the image. Open a pull request with the build output before and after.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
A pull request that changes a few lines of the Dockerfile and nothing else. The description shows the failing step from the original build with pip's message, the list of options with one sentence each on why it was or was not chosen, and the tail of the successful build followed by the output of the tool's help command from inside the new image. It names the base tag it pinned and the release that tag was pointing at when the build broke.
A reviewer checks that the image still does its job: the ENTRYPOINT line and entrypoint.sh are untouched, and the pipenv install step still runs after the Pipfile is copied. They also decide on the two reported items. Committing a Pipfile.lock and adding a workflow job that builds the image are both follow-ups the description proposes without doing, because each changes more than the bug required.
Run it on every image build that fails on pip
If a workflow builds your images, let its failure start the run. Add an automation on the Project with a github trigger on workflow_run.failure and the prompt above; the failed run is appended after the prompt as event text. The prompt is the only instruction, so a failure with a different cause ends in a short report and no pull request.
If nothing builds the image in CI, as in the example repository, a schedule trigger with a weekly cron does the job a pipeline would have done: the agent builds every Dockerfile and opens a pull request only when one fails with this error. The automation's max runs per hour limits how many start if several repositories break in the same week.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
The quickest fix for this error is a flag whose name says what it risks, and it is the fix a person reaches for at the end of a long day because the build goes green. Choosing better takes a few builds: one to reproduce, one per candidate, one to run the container. The agent does those in a sandbox with its own Docker daemon, where a failed layer or a half-built image costs nothing on anyone's machine, and the output of each build is kept with the run.
It also reads the file for the reason the error appeared now. A laptop often still holds the old base image in its cache and builds without complaint, which is how a broken Dockerfile stays broken for months. The sandbox pulls the tag fresh, so it sees what a new contributor or a clean runner sees.
Frequently asked questions
Is --break-system-packages safe inside a container?
It is less dangerous than on a workstation, because the image is rebuilt from scratch and nothing else depends on its system Python. It can still replace a module that an apt package in the same image needs, and it hides the fact that the image mixes two package managers in one directory. The agent uses it only when the alternatives do not build, and says so in the pull request.
Why did the build work last month?
Because FROM ubuntu:latest or FROM debian:latest named a different release then. When the tag moved to a release that marks its Python as externally managed, the same pip3 install line began to fail. Pinning the tag to a release means the image changes when you edit the file, not when the registry does.
Do official python images have this problem?
No. They compile Python into /usr/local and ship no EXTERNALLY-MANAGED file, so pip install works as root. The error can come back if you install python3-pip from apt in such an image and call the distribution's pip instead of the one the image provides.
Does it work for Debian-based images too?
Yes. Debian 12 adopted the same rule, so debian:bookworm and the slim variants behave like recent Ubuntu. The agent checks for the marker file in the base image it pulls rather than guessing from the tag name.