What the agent does
Werkzeug 3.0.0, released on 30 September 2023, removed werkzeug.urls.url_decode. Flask-Login 0.6.2, from July 2022, imports it at module level, so on any environment where the two meet, from flask_login import LoginManager fails with ImportError: cannot import name 'url_decode' from 'werkzeug.urls'. Flask-Login 0.6.3, released 30 October 2023, dropped the import and declares only Flask >=1.0.4 and Werkzeug >=1.0.1. The error is not a bug in your code and not in Werkzeug; it is a one-month gap between two releases, and it opens the moment Werkzeug moves while Flask-Login stays.
miguelgrinberg/flask-oauth-example, a small app that signs people in with Google or GitHub, shows the usual shape. Its requirements.txt is a frozen set from May 2023: Flask==2.3.2, Flask-Login==0.6.2, Flask-SQLAlchemy==3.0.3, Werkzeug==2.3.4, SQLAlchemy==2.0.15, requests==2.31.0. app.py imports LoginManager, UserMixin, login_user, logout_user and current_user from flask_login, calls logout_user() in its /logout route and login_user(user) at the end of the OAuth callback, and creates its tables under with app.app_context(). Installed as pinned, it imports. Then one of two routine things happens: a security bump moves Werkzeug to 3.x, or Flask is bumped to 3.0.0, which itself requires Werkzeug>=3.0.0. Either way the next import app fails inside flask_login on the url_decode line.
The agent reproduces both halves on a clean environment: the pinned set imports, and the same set with Werkzeug upgraded (3.1.9 today) does not. It then reads requirements.txt for every package that imports Werkzeug privately, and checks each against the Werkzeug it is about to live with. Flask-Login moves to 0.6.3, the first release that imports on Werkzeug 3; Flask 2.3.2 is already compatible with Werkzeug 3, so it may stay or move to 3.x in the same change, and the pull request says which. Nothing in app.py changes: url_decode was Flask-Login's dependency, not the app's.
Then it starts the app. flask --app app routes lists the five routes, import app succeeds, and a request to / renders the index page, which is as far as the app goes without real OAuth credentials. The agent does not add werkzeug<3 to the requirements to make the old Flask-Login import: that would freeze a web server library on a line that no longer receives fixes, to spare a one-line bump.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "This Flask app fails at import with \"ImportError: cannot import name 'url_decode' from 'werkzeug.urls'\" after Werkzeug or Flask was upgraded. Read the dependency files and report the pinned versions of flask, flask-login and werkzeug. Create a clean virtual environment on a current Python, install the pins as written, and confirm whether the app imports; then install the upgrade that triggered the report (werkzeug or flask) and save the traceback. Identify which installed package imports url_decode, and for every package in the requirements that depends on Werkzeug privately, find the first release that imports cleanly on the new Werkzeug. Bump flask-login (and only what the new Werkzeug requires) in the requirements file; do not add an upper bound on werkzeug to hide the error, and do not change application code that did not fail. Install the updated pins, import the app, list its routes, and request its index page with an HTTP client. Open a pull request with the before and after traceback, the exact pins changed and why each one moved, and the commands that now succeed.",
"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 one or two lines in requirements.txt: Flask-Login==0.6.2 becomes Flask-Login==0.6.3, and Werkzeug and optionally Flask move to the 3.x releases that triggered the report. No Python file changes. The description shows the pinned set importing, the upgraded set failing with the url_decode traceback, and the bumped set importing again, each as a command and its output, together with the route list and the status of a request to /.
What a reviewer checks is that each moved pin has a stated reason. Flask-Login moved because 0.6.2 imports a name Werkzeug 3 removed and 0.6.3 does not; Werkzeug moved because that was the upgrade under review; Flask moved, if it did, because Flask 3.0.0 requires Werkzeug 3. A pin that moved for no stated reason is a question for the author, not a merge.
The pull request also says what it did not test. Sign-in through Google or GitHub needs client credentials the sandbox does not have, so login_user and logout_user are exercised only as far as importing and routing; a reviewer with credentials runs one sign-in on the branch before merging.
Run it on every dependency bump pull request
The bump that breaks this import usually arrives as a security pull request for Werkzeug, so that is the moment to check. Give the Project an automation with a github trigger on pull_request.opened and a prompt that tells the agent to install the branch's pins into a clean environment, import the app, and report any ImportError from a package that imports Werkzeug privately, with the first release of that package that imports cleanly. The trigger adds the pull request to the prompt; the Werkzeug bump then carries the matching Flask-Login bump before anyone merges a branch that cannot start. A pull request a bot opens fires no github trigger, so a Dependabot bump is checked by a schedule trigger with a weekly cron whose prompt tells the agent to check the open dependency pull requests.
For a fleet of Flask services with frozen requirements, start the request above once per repository from a script with an API key, and read each session's pr_url when its run.completed webhook arrives. Each run has its own environment, and runs past the key's max_concurrent limit are accepted and wait as queued.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
The bump is one line, but the proof takes three environments: the pins as written, the pins with the upgrade that broke them, and the pins after the fix, each with an import and a request against the real app. An agent in a sandbox builds all three with the real resolver and keeps each command's output in the session, so the pull request is reviewable from its description alone.
It also answers the next question before it is asked: which other pinned package imports Werkzeug privately and will break on the same day. On a laptop with a long-lived virtual environment that question never comes up, because Werkzeug there is still 2.3 and nothing has failed yet.
Frequently asked questions
Is this a Werkzeug bug?
No. Werkzeug 3.0.0 removed url_decode on purpose, and Flask-Login 0.6.2 was the last release to import it. Flask-Login 0.6.3, released a month later, imports fine on Werkzeug 3.1.9 and declares only Werkzeug >=1.0.1.
Can I pin werkzeug below 3 instead?
It makes the old Flask-Login import again, but it also blocks Flask 3, which requires Werkzeug 3, and keeps the WSGI toolkit under your app on a line that no longer gets fixes. Bumping Flask-Login is one line and removes the conflict. The request above tells the agent not to add that upper bound.
Does Flask itself need to move?
Not for this error. Flask 2.3.2 imports on Werkzeug 3, so the fixture runs with only Flask-Login bumped. If the report came from a Flask 3 upgrade, Flask moves as well, and the pull request says that is why.
Will login_user and logout_user behave the same on 0.6.3?
The agent verifies the import, the route list and a request to the index page, which is what the sandbox can do without OAuth credentials. The sign-in flow itself is listed as untested in the pull request so a reviewer with credentials runs it once.
Why not catch the ImportError and fall back?
Because the import is inside Flask-Login, not in your code, and a fallback would hide the version mismatch instead of resolving it. The agent changes the pin that causes the error and nothing in the application.
More jobs like this: Fix a bug from an alert
- Fix "cannot load such file -- net/smtp (LoadError)" on Ruby 3.1 and Later (Ruby)
- Fix "Can't load plugin: sqlalchemy.dialects:postgres" in a Flask App (SQLAlchemy)
- Fix "Error: No such option '-A'" when a Celery worker starts after moving to Celery 5 (Celery)
- Fix "Class constructor MongoStore cannot be invoked without 'new'" After Upgrading connect-mongo (connect-mongo)
- Fix "TypeError: CliRunner.__init__() got an unexpected keyword argument 'mix_stderr'" in Click 8.2 (Click)
- Fix Cloudflare Worker Errors From Its Logs (Cloudflare Workers)