What the agent does
Fabric 2.0 replaced the whole fabric.api module, and an unpinned pip install fabric now resolves Fabric 3.2.3 with invoke 2.2.1 under it. A fabfile that opens with from fabric.api import env, task, run, local, get, sudo dies on that line with ModuleNotFoundError: No module named 'fabric.api'; so does from fabric.context_managers import cd, lcd, prefix, shell_env. The old names did not move, they were redesigned: Fabric 3 exposes Connection and task from the top-level package, and Connection carries run, sudo, local, get, put, cd and prefix as methods and context managers, while the environment a command runs under is the env argument of run.
In a Flask project like imwilsonxu/fbone, requirements.txt lists Fabric unpinned at the top of a Python 2 era list that also names MySQL-python, pycrypto and wsgiref, and the README's usage section is four Fabric commands: fab setup_python_macos, fab bootstrap, fab test and fab debug. fabfile.py defines eight tasks with the 1.x API: env.user, env.hosts and env.remote_interrupt at the top; bootstrap, debug and test wrap local(...) calls in with shell_env(FLASK_APP='wsgi.py', FLASK_DEBUG="1"); deploy pushes locally and then runs git pull and touch wsgi.py inside with cd(...) on the server; and syncdb dumps MySQL remotely inside with cd("/tmp"), fetches the archive with get, and imports it inside with lcd("/tmp"). The file imports prefix and never uses it.
The agent reproduces the import error in a clean virtual environment, then checks the quick fix before recommending against it: pip install "fabric<2" installs Fabric 1.15.0 with paramiko 2.12.0, and both old imports work on Python 3.11. But python -m py_compile fabfile.py fails regardless of Fabric version, because syncdb has two bare print "..." statements, so the fabfile has not loaded on Python 3 at all; the pin would only move the error one line down. The port is the real fix, and the agent reads the installed Fabric and invoke rather than a tutorial: it confirms that Connection.run accepts env={...} for what shell_env did, that with c.cd(...) prefixes the remote command, and which of cd and prefix apply to local before translating lcd.
Each task becomes a function that takes the context as its first argument, with the host list moved from env.hosts to the command line or the task's own hosts, and every local, run, get and cd becomes a call on that context. The print statements get parentheses, prefix is dropped from the imports, and requirements.txt pins fabric>=3. Then it proves the file loads: fab --list prints the eight tasks, and each local-only task runs with --dry so the commands echo without touching the machine. The remote tasks are not executed, since the sandbox has no server to reach; the pull request shows the dry-run output for them instead and says so.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "The fabfile in this repository fails with ModuleNotFoundError: No module named 'fabric.api'. In a clean virtual environment, install the project's Fabric as listed and report the resolved versions of fabric, invoke and paramiko and the traceback; then install fabric<2 in a second environment and report whether the old imports work and whether python -m py_compile fabfile.py passes. Port fabfile.py to the installed Fabric 3: from fabric import Connection, task; each task takes a context argument; local, run, sudo, get, cd and prefix become calls on it; shell_env becomes the env argument of run; env.hosts moves to the task's hosts or the command line. Check each of those against the installed package's signatures, not from memory. Fix Python 2 syntax the compile step reports and drop unused imports. Pin fabric to 3 or newer in requirements.txt. Run fab --list, run every task that only touches the local machine with --dry, and include that output; do not run anything that would reach a remote host. Open a pull request with the port, the two environment reports and the dry-run output.",
"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 rewrites fabfile.py and pins Fabric in requirements.txt. The description opens with the two environments: the traceback from the fresh install with its resolved fabric, invoke and paramiko versions, and the Fabric 1.15 install that imports but still fails to compile, so a reviewer sees why a pin alone was rejected. A table maps each old name used in the file to its Fabric 3 form and the line it now sits on.
Below it is the fab --list output naming every task and the --dry transcript of each local task, with the commands that would have run. The remote tasks appear in the same transcript as echoed commands only; the session's record keeps every command the agent ran to get there.
Before merging, a reviewer checks the host and user that deploy and syncdb now take from the command line, that the MySQL credentials the old file held in module constants were not pasted into the new one, and that any script or CI step calling fab with 1.x flags is updated with it.
Run it on every new Python 3 environment or CI image
This error appears the first time a Fabric 1 project is installed somewhere new: a rebuilt container, a new laptop, a CI image without the old pin. When that install fails on the import, a handler on your server reads the failure, and sends this request with POST /o/{org}/sessions with the repository in resources and the failing command's output appended to input. Give it a request_id that is a UUID v5 of the CI run id, so a retried delivery returns the run that already started instead of opening a second pull request.
A company with several projects still carrying a 1.x fabfile starts one run per repository from a schedule or a script, one request each with that repository in resources, and reviews the ports as they arrive.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
The port is mechanical but the checks are not: it takes two virtual environments, a read of the installed invoke's signatures, a compile step that surfaces the Python 2 remnants, and dry runs of every task to show the file loads. In a Rush sandbox the agent does that on its own disk, with no SSH key and no server in reach, so a deploy task that still points at production cannot run by accident.
What comes back is evidence rather than a diff: the transcript holds both installs, the compile error, the task list and the dry-run commands. A team with a handful of old fabfiles starts one run per repository with the same request, up to the key's max_concurrent limit at once, and the rest queue.
Frequently asked questions
Can I just pin fabric<2?
It installs: Fabric 1.15.0 runs on Python 3.11 and the fabric.api imports work. In the example it does not help, because the fabfile has Python 2 print statements and fails to compile before any task runs. The agent reports both facts and ports the file, which is also the only path that keeps receiving fixes.
What happened to env.hosts and shell_env?
Fabric 3 has no global env. A task takes a context, a Connection to one host when run with a host list, and the environment a command needs is the env argument of that context's run. The agent verifies the env argument against the installed invoke before using it, since it is not in the method's printed signature.
Will the agent run my deploy task?
No. It runs fab --list and the tasks that only touch the local machine with --dry, which echoes commands without executing them, and treats anything that opens a connection as remote. The pull request shows the echoed commands for those tasks and says they were not run.
What about the rest of a Python 2 era requirements file?
The agent pins Fabric and leaves the other entries alone, since this request is about the fabfile. It lists packages it noticed that have no Python 3 release, such as MySQL-python, in the pull request as a follow-up rather than changing them in the same change.
More jobs like this: Fix a bug from an alert
- Fix "ModuleNotFoundError: No module named 'imghdr'" on Python 3.13 (imghdr)
- Fix ModuleNotFoundError: No module named 'imp' on Python 3.12 (imp)
- Fix "ModuleNotFoundError: No module named 'imp'" on Python 3.12 (Python)
- Fix "ModuleNotFoundError: No module named 'kafka.vendor.six.moves'" on Python 3.12 (kafka-python)
- Fix "ModuleNotFoundError: No module named 'moviepy.editor'" (MoviePy)
- Fix "ModuleNotFoundError: No module named 'pip.req'" in setup.py (pip)