What the agent does
The message is raised by Flask, and the application's own code is usually innocent. Take a small app like thedataincubator/flask-framework. Its requirements.txt has two lines, flask==2.2.2 and gunicorn, and app.py imports Flask and render_template and nothing else. No file in the repository mentions Werkzeug. So the agent does not start by searching the code for url_quote. It installs the requirements file as written into an empty virtual environment, lists what the resolver chose, and runs python -c "import app". Flask is 2.2.2 as pinned, Werkzeug beside it is a 3.x release, and the import stops at line 30 of Flask's flask/app.py, from werkzeug.urls import url_quote, with the error in the title.
Next it explains why an app nobody touched stopped starting. Flask 2.2.2's package metadata asks for Werkzeug>=2.2.2 and sets no upper limit. Werkzeug 3.0.0 reached PyPI on 2023-09-30 and removed the URL helpers that Flask 2.2 imports. The fixture's last commit is from January 2023, so every install before that autumn worked and every clean install since fails, with no change in the repository to point at. That is also why the report arrives as a failed deploy. Started under the server its requirements name, gunicorn app:app logs the same ImportError in the worker and the master exits with Worker failed to boot.
Then it tries the fixes people suggest, each in its own fresh environment, and requests /, /about and a path that does not exist through Flask's test client. Adding werkzeug<3 keeps Flask where it is and brings Werkzeug 2.3.8: the three requests answer 200, 200 and 404, but with warnings turned into errors the import fails on 'werkzeug.urls.url_parse' is deprecated and will be removed in Werkzeug 3.0, so the pin holds the app on a line that has already said goodbye. Moving only to Flask 2.2.5 looks like the smallest step and is a trap: the import succeeds on Werkzeug 3, and app.test_client() then raises AttributeError: module 'werkzeug' has no attribute '__version__' from flask/testing.py, which means a server that boots and a test suite that cannot. Flask 2.3.3 and Flask 3.1 both pass all three requests on Werkzeug 3.
The agent picks the release that fits the interpreter the app is deployed on. The fixture's README says the hosted copy runs Python 3.9.0, set through a PYTHON_VERSION variable, and Flask 3.1 declares Python 3.9 or newer, so it qualifies; an app on 3.8 would take Flask 3.0, the last line that still accepts it. It then closes the hole that caused the failure: gunicorn has no version at all, and Jinja2, click and itsdangerous are chosen fresh on every build. The pull request pins the direct dependencies and adds a compiled lock of the transitive ones. Because the repository has no tests, it also adds one small test that requests the two pages, so the next surprise from the resolver fails in CI and not on the host.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "This Flask app fails to start with \"ImportError: cannot import name 'url_quote' from 'werkzeug.urls'\". Do not start by editing code. Create an empty virtual environment, install the requirements file exactly as it is, and list the installed versions of Flask, Werkzeug, Jinja2, click, itsdangerous and the WSGI server. Reproduce the error by importing the application module, and again by starting it with the command the project uses to serve it, and save both outputs. From the installed package metadata, state which dependency range allowed the incompatible version and the date that version was published. Then test each of these in its own fresh environment: pinning Werkzeug below 3 with Flask unchanged; the newest patch release of the current Flask minor; the newest release of the next Flask minor; and the newest Flask. For each one, import the app, request every route plus one unknown path through the test client, repeat the import with warnings as errors, and record the result. Check the Python version the project deploys on against each candidate's requires-python. Choose the newest option that passes everything on that Python version. Pin every direct dependency, add a lock or constraints file for the transitive ones using a tool the project already uses if there is one, and add a minimal test that requests each route if the repository has no tests. If the project's own code imports anything from werkzeug.urls, replace it with the urllib.parse equivalent and show the outputs match for a string with a space and a non-ASCII character. Open a pull request with the table of options and results.",
"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 whose diff is mostly requirements.txt: Flask moved to the chosen release, gunicorn given a version, and a lock file for everything pip used to pick on its own. A new test file requests each route. Application code and templates are untouched unless the project itself imported a removed helper. The description opens with the reproduction, the resolver's version list and the two failing commands, and then gives one row per option: what was installed, whether the import worked, the status of each request, and whether the import survived warnings as errors.
A reviewer reads the row for the option that was not taken as closely as the one that was. If the team prefers the werkzeug<3 pin for now, the evidence for that choice is already in the table, along with the deprecation text that says how long it lasts. They also check the Python version named in the description against the host, since the newest Flask does not install on older interpreters, and confirm the lock file was produced by the stated command. When an option fails in a way the agent did not expect, the pull request says so and the session is left for review.
Run it on every failed deploy
A resolver failure shows up when something rebuilds the environment: a deploy, a new container image, a teammate's first install. If the build runs in GitHub Actions, an automation with a github trigger on workflow_run.failure starts a run when the workflow fails, and the failure event is placed after the saved prompt. For a hosting platform that sends its own deploy notifications, check whether it can send an Authorization: Bearer header. If it cannot, a small handler on your server receives the notification and posts the build log to a webhook trigger's URL with the trigger's secret.
A schedule catches it earlier. A schedule trigger with every set to 1d runs the same prompt each night: install from scratch, import the app, request the routes. The night an upstream release breaks a clean install, the result is a pull request waiting in the morning instead of a deploy that fails at the worst moment. Keep the automation's max runs per hour low; one run covers the repository.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
This failure cannot be seen on a machine that already has a working environment. A laptop that installed the app last year still has Werkzeug 2 in its virtualenv, the app starts, and the developer concludes the host is at fault. A Rush run begins in a new sandbox with nothing installed, which is the same position the deploy is in, so the first install reproduces the error and each candidate fix gets an environment that no earlier attempt has touched.
It also turns advice into evidence. The usual answers to this error are single lines passed around without the conditions attached. Here four of them are run against the real routes, including the one that boots and then breaks the test client, and every command with its output stays in the session's transcript. The reviewer merges a choice they can check, and the lock file means the same question does not come back at the next upstream release.
Frequently asked questions
Why did this error appear when I changed nothing?
Because the requirements file pins Flask and leaves Werkzeug to the resolver. Flask 2.2 accepts any Werkzeug from 2.2.2 up, so a clean install after Werkzeug 3.0.0 was published gets a version Flask 2.2 cannot import from. An existing environment keeps working until it is rebuilt.
Is pinning werkzeug<3 enough?
It makes the app start. In the fixture, Flask 2.2.2 with Werkzeug 2.3.8 serves every route. It also keeps you on a Werkzeug line whose own warnings say the functions are going away, and running with warnings as errors fails at import. Treat it as a holding fix and plan the Flask upgrade.
Which Flask versions work with Werkzeug 3?
On the fixture, Flask 2.3.3 and Flask 3.1 import and serve every route with Werkzeug 3. Flask 2.2.5 imports but its test client fails on current Werkzeug 3 releases, so a project with tests should not stop there. The agent tests the versions against your routes instead of assuming.
What if my own code imports url_quote?
Then the agent replaces it. Werkzeug 2.3's deprecation message names the substitute, urllib.parse.quote, and the prompt asks for the two to be compared on a string with a space and a non-ASCII character before the import is changed. Other helpers from werkzeug.urls get the same treatment, one at a time.
Does the run deploy the fix?
No. It opens a pull request and stops. Your pipeline deploys after someone merges it, and the test the pull request adds runs in your CI from then on.
More Werkzeug jobs
More jobs like this: Fix a bug from an alert
- Fix "TypeError: __init__() got an unexpected keyword argument 'size'" in gensim 4 (gensim)
- Fix "RuntimeError: Working outside of application context" from db.create_all() in Flask-SQLAlchemy 3 (Flask-SQLAlchemy)
- Fix "AttributeError: module 'lib' has no attribute 'X509_V_FLAG_CB_ISSUER_CHECK'" From pyOpenSSL (pyOpenSSL)