All jobs

Fix "ForwardRef._evaluate() missing 1 required keyword-only argument: 'recursive_guard'" in Pydantic v1

Yes. An agent traces the error to a Pydantic v1 pin older than 1.10.16 on Python 3.12.4 or later, moves the pin and shows the app importing again.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The message reads TypeError: ForwardRef._evaluate() missing 1 required keyword-only argument: 'recursive_guard', and the last frames of the traceback are in pydantic/typing.py, in evaluate_forwardref. It is raised when Pydantic v1 resolves a type annotation that is stored as a string. Old 1.x releases call a private method of Python's typing module with three positional arguments, and newer interpreters made the last of those keyword-only. A model with plain annotations still works, which is what makes the failure confusing: import pydantic succeeds, a simple model validates, and then importing a framework built on Pydantic fails.

Krish2205/UniVerse---Multilingual-AI-chatbot has the combination that produces it. backend/Dockerfile starts FROM python:3.12-slim, installs pydantic==1.10.13 ahead of the requirements file, installs requirements.txt (which pins fastapi==0.104.1 and pydantic==1.10.13 again), and then runs pip install --force-reinstall --no-deps pydantic==1.10.13 so that nothing can move it. Its comments give the reason, packages installed "in specific order to avoid conflicts" with Pydantic v1 first, and the neighbouring pins are langchain==0.1.0 and chromadb==0.4.22. The Dockerfile even verifies its work with python -c "import pydantic; print(...)". That check passes and proves nothing, because the error does not come from importing Pydantic. With those two pins on Python 3.12.8, import fastapi raises the recursive_guard error from FastAPI's own models, before backend/main.py reaches its first route.

The agent reads the Dockerfile, the requirements file and the entry point, then reproduces the failure in a clean environment on the image's Python line, not on whatever interpreter happens to be installed. It bisects the pin instead of guessing. On Python 3.12.8, Pydantic 1.10.12, 1.10.13 and 1.10.15 all raise the error on a model with a forward reference; 1.10.16 and later do not. On Python 3.13 the same holds for 1.10.13 against 1.10.18. So the smallest fix keeps the project on v1 and moves the pin to a 1.10 release from 1.10.16 upward, in both places the Dockerfile names it and in requirements.txt.

Then it checks that the rest of the stack accepts the new pin. It installs the full requirements file, imports fastapi, langchain and chromadb, and starts the application far enough to load its models: ChatRequest, ChatResponse and the others in backend/main.py. It replaces the Dockerfile's version print with an import of the application module, a check that would have caught this. It does not migrate the project to Pydantic v2. That is a larger change with its own breakages, and the pull request says so in one sentence and leaves it as a follow-up.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "The application fails at import with \"TypeError: ForwardRef._evaluate() missing 1 required keyword-only argument: 'recursive_guard'\", raised from pydantic/typing.py. Find every place the Pydantic version is set: requirements and constraints files, pyproject.toml, lockfiles, and any pip install line in Dockerfiles, CI workflows and scripts (including --force-reinstall or --no-deps lines). Find the exact Python version the project runs on from its Dockerfiles, CI and runtime config. Create a clean environment on that Python minor version at its latest patch release and reproduce the error first: install the pinned versions, then import the application's entry module. Keep the full traceback. Stay on Pydantic v1: move the pin to the lowest 1.10.x release that no longer raises the error on that Python (1.10.16 or later), and change it consistently everywhere it is set. Do not migrate to Pydantic v2 and do not change the Python version. Then install the complete dependency set and confirm that every package that depends on Pydantic still resolves and imports; name each one you checked. Start the application far enough to import all of its models and routes, and run the test suite if there is one. If the build has a verification step that only imports pydantic or prints its version, replace it with one that imports the application module. If any dependency refuses the new pin, stop and report the conflict with the resolver output instead of forcing it. Open a pull request with the failing traceback, the versions you tried and what each did, and the passing output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. 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.
  2. 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.
  3. 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 edits the Pydantic pin wherever it appears, which in a layout like the fixture's means three lines across two files. The description gives the traceback from before the change and a short table of the versions tried on the project's Python with the result of each, so the reviewer can see why the chosen release is the lowest one that works and not simply the newest.

It also lists the packages that depend on Pydantic and what the agent did to check each: resolved, imported, or exercised by a test. If the application has tests they run and their output is quoted. If it has none, the pull request shows the application module importing and its models being constructed, and says plainly that this is an import check and not a behavioural test.

The reviewer's job is the compatibility question. A 1.10 patch release is meant to be safe, but a project that force-reinstalls its pin has been bitten by a resolver before, and the reason may still apply. Read the resolver output in the description, and build the image once before merging if the container is how the service ships.

Run it on every crash on startup

This one surfaces as a container that exits on start after a base image rebuild, because a tag such as python:3.12-slim moves to newer patch releases on its own. If your alerting can send a custom Authorization header, as a Grafana contact point can, point it at a webhook trigger on an automation in the Project that holds the repository; the alert's payload reaches the agent after the prompt. Services that sign their own requests cannot call the trigger directly, so for those a small handler on your server receives the alert and forwards it.

The other route is your deploy pipeline. A step that runs when the smoke test fails can search the container log for recursive_guard and send the request above with your API key. Give it a request_id that is a UUID v5 of the image digest, so that repeated restarts of one bad image start one run.

The use case this job follows, with its automation and trigger: Fix a bug from an alert.

Why run it on Rush?

The error depends on the patch release of Python, which is the detail a laptop gets wrong. A developer on 3.12.3 cannot reproduce what a container on 3.12.8 does, and will reasonably conclude the code is fine. The agent installs the interpreter the image uses and works there, in a sandbox with no site-packages left over from another project to blur which Pydantic is being imported.

Bisecting a pin is also dull work that is easy to cut short. The run installs each candidate release, runs the same script against it and keeps every result in the session transcript. The claim that 1.10.16 is the first release that works rests on recorded output from the releases either side of it, and anyone reviewing the pull request can read that output.

Frequently asked questions

Which Python versions trigger this?

It reproduces on Python 3.12.8 with Pydantic 1.10.15 and older, and on Python 3.13.1 with 1.10.13. The change in Python's typing module arrived in a 3.12 patch release, which is why a project can break without changing its minor version. A floating base image tag is the usual way that happens.

Do I have to migrate to Pydantic v2?

No. A newer 1.10 release fixes the call, and on Python 3.12.8 FastAPI 0.104.1 imports cleanly with Pydantic 1.10.16 and with 1.10.24. Moving to v2 is a separate project that touches validators, config classes and every library pinned to v1. The agent keeps the fix small and notes the migration as follow-up work.

Why does import pydantic work while my app still crashes?

Importing Pydantic evaluates no forward references. The failing call runs only when a model's annotations are strings, through from __future__ import annotations or a model that refers to itself. FastAPI's OpenAPI models do this, so import fastapi is often the first line to fail.

I do not use Pydantic directly. Where is it coming from?

From a dependency: FastAPI and LangChain, among many others, are built on Pydantic, and some of their older releases hold it on v1. The agent prints the dependency tree, names the package that holds the pin, and checks whether a newer release of that package accepts a fixed Pydantic.

Would pinning Python to an older patch release work?

It hides the problem until the next image rebuild or security update, and it leaves the project on an interpreter that no longer receives fixes. The agent does not change the Python version. If you need an immediate stopgap it is safer to pin the Pydantic release than the interpreter.

More Pydantic jobs

More jobs like this: Fix a bug from an alert

Keep reading