What the agent does
The agent starts from the install, because this error is produced by the resolver and not by any line of your code. In a project like Widdershin/flask-desktop, requirements.txt pins Flask==1.0, Jinja2==2.11.3, Werkzeug==0.15.5 and itsdangerous==0.24, and leaves one line open: MarkupSafe>=1.1.1. setup.py reads that file into install_requires, so everyone who installs the package inherits the open range. A fresh environment today resolves MarkupSafe 3.0.4, and import flask stops inside Jinja2 at jinja2/filters.py line 13, from markupsafe import soft_unicode. MarkupSafe renamed that function to soft_str and removed the old name in 2.1.0. Jinja2 2.11.3 still asks for it.
Next it works out which Python the project can install on at all, since that limits the choices. Here PySide2==5.15.2 declares that it needs a Python below 3.10, so the agent builds its environment on 3.9, installs the file as written and quotes the traceback. The project has no tests and no CI workflow, so it writes a ten-line check of its own: a Flask app with one route that renders a template containing a value with angle brackets, called through app.test_client(). That exercises the Flask, Jinja2 and MarkupSafe chain without opening the Qt window that webui/webui.py creates.
Then it tries each fix and keeps the evidence. Capping the range as MarkupSafe>=1.1.1,<2.1 resolves 2.0.1, and the check renders and escapes the value. Raising Jinja2 alone does not work: with Jinja2 3 installed, Flask 1.0 fails sooner, with cannot import name 'Markup' from 'jinja2', because that old Flask imports Markup and escape from Jinja2 and newer Jinja2 no longer exports them. Moving the whole set forward together does work on the same Python 3.9: Flask 3.1.3 with Jinja2 3.1.6 and MarkupSafe 3.0.4 passes the check, and webui/webui.py still imports, since its only use of Flask is flask_app.run(debug=debug, host=host, port=port, use_reloader=False).
The prompt decides which of the two working fixes the pull request carries. By default the agent makes the smallest change that restores the install, the one-line cap, and writes up the full upgrade as a second option with what it tested and what it could not. It does not add soft_unicode back with a shim or patch files inside site-packages.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "This project fails on a fresh install with: ImportError: cannot import name 'soft_unicode' from 'markupsafe'. Fix it. Read every dependency file (requirements files, setup.py, setup.cfg, pyproject.toml, lock files) and list the version constraint on Flask, Jinja2, MarkupSafe, Werkzeug and itsdangerous, and say which of them are unpinned or open-ended. Work out which Python versions the pinned packages can install on and use one of them. In a clean virtual environment install the project exactly as its files say, reproduce the error and quote the traceback and the resolved versions. If the project has tests, run them; if it has none, write the smallest check that imports the app and renders one template through the test client, without starting a server or a GUI. Try these fixes in separate environments and report each result: an upper bound on MarkupSafe that still has the removed name; upgrading Jinja2 only; upgrading Flask, Jinja2, Werkzeug, itsdangerous and MarkupSafe together. Put the smallest fix that passes the check in the pull request, and describe the full upgrade as a follow-up with what you tested. Do not vendor or monkeypatch markupsafe, and do not edit installed packages. Open a pull request with the traceback before, the resolved versions after, and the check's 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 changes one line of requirements.txt, from MarkupSafe>=1.1.1 to MarkupSafe>=1.1.1,<2.1. Because setup.py builds install_requires from that file, the same line fixes pip install of the package for its users. The description quotes the traceback ending in jinja2/filters.py, the versions the resolver chose before and after, and the output of the render check on both.
Below that it lays out the larger option as a table: each of the five web packages, its pinned version and the version the upgrade test resolved. It states plainly what the upgrade test covered, one rendered template and an import of webui.webui, and what it did not, which is the Qt window itself. A reviewer who owns a desktop machine is the one who can run examples/test_app.py and watch the window open.
What a reviewer checks before merging is the cap's cost. MarkupSafe 2.0.1 publishes wheels for CPython 3.6 through 3.10 and nothing newer, so the one-line fix holds only while the project stays on those interpreters. Here PySide2 already keeps it below 3.10, and the description says that the two limits should be lifted together.
Run it on every image build that fails on this import
This error arrives without a commit: an image is rebuilt, the resolver picks a newer MarkupSafe, and the app stops at import. Catch it where the build runs. Add an automation with a webhook trigger and the prompt above to the Project that holds the repository, then add a step to the build workflow that runs python -c "import flask" after the install. When that step fails and its output contains soft_unicode, a following step posts the output to the trigger's URL with Authorization: Bearer and the trigger's secret, kept as a repository secret. The posted text is placed after the saved prompt as the event.
Send an Idempotency-Key header to the trigger's URL, set to the workflow run id, so a re-run of the failed job starts nothing new. If several repositories share the same base image they tend to break in the same hour, so set the automation's max runs per hour with that in mind. An event past the cap waits as a queued run until the hour has room.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
Whether you see this error depends on when your environment was created. A laptop virtualenv built two years ago still holds an old MarkupSafe and imports cleanly, which is why the usual first reply to this bug report is that it works locally. The run installs from the repository's files into an empty environment in its own sandbox, so it sees what your image build sees, and the session transcript keeps each install command with the versions it resolved.
The three candidate fixes are also cheap to state and tedious to compare. Each needs its own environment, an interpreter the pins accept, and the same check run against it. The agent does all three and brings back the one failure that matters for planning: upgrading Jinja2 on its own trades this ImportError for another one in Flask.
Frequently asked questions
Why did this start failing when nothing in my repository changed?
One requirement in the chain has no upper bound, so every fresh install takes the newest MarkupSafe. Jinja2 2.x imports soft_unicode, and MarkupSafe removed that name in 2.1.0. Any environment created after that release resolves a version without it. Existing environments keep working until they are rebuilt.
Is pinning MarkupSafe to 2.0.1 a real fix or a workaround?
It is a correct statement of what Jinja2 2.x needs, so it belongs in the file either way. It is also a ceiling: 2.0.1 has no wheels past CPython 3.10. The agent applies the cap to restore the install and reports the upgrade path separately, so the cap does not become permanent by default.
Can I just upgrade Jinja2?
Only if Flask moves with it. Flask 1.x imports Markup and escape from Jinja2, and Jinja2 3.1 dropped both, so the app fails with a different ImportError. The agent tests that combination and shows the traceback so the pull request does not suggest it.
My project has a lock file. Does this still apply?
A lock file that pins MarkupSafe protects installs made from it. The error then appears in the paths that bypass the lock: a Dockerfile that installs from requirements.in, a pip install . of the package, or a CI job that upgrades everything. The agent reads each install command it can find and reports which ones use the lock.
Will the agent start my application?
It imports it and calls it through Flask's test client. It does not bind a port, open a browser window or start a GUI toolkit. For a desktop wrapper like this one the pull request says that the window was not exercised.
More jobs like this: Fix a bug from an alert
- Fix "AttributeError: module 'matplotlib.cm' has no attribute 'get_cmap'" on Matplotlib 3.9 (Matplotlib)
- Fix "TypeError: Missing parameter name at 1" After Upgrading to Express 5 (path-to-regexp)
- Fix "AttributeError: module 'bcrypt' has no attribute '__about__'" with passlib (passlib)
- Fix "AttributeError: module 'cv2' has no attribute 'xfeatures2d'" by Moving SIFT to cv2.SIFT_create (opencv-python)
- Fix "AttributeError: module 'emoji' has no attribute 'UNICODE_EMOJI'" (emoji)
- Fix Moment's "Value Provided Is Not in a Recognized RFC2822 or ISO Format" Warning (Moment.js)