What the agent does
The error text gives the first step, and the first step is not enough. The agent begins by reading how settings are defined and, just as important, what pins them. In snowzach/doods2, line 2 of config.py is from pydantic import BaseSettings, Extra, eleven classes in that file inherit from BaseSettings, and seven of them carry an inner class Config that sets extra = Extra.ignore, five with an env_prefix such as server_ or mqtt_. requirements.txt pins pydantic==1.10.14 and fastapi==0.70.1. That second pin matters: FastAPI 0.70.1 declares pydantic<2.0.0, so a resolver refuses to install it beside Pydantic 2 at all. Anyone seeing this error in such a project got there by upgrading one package without the other, and the agent says so before it edits, because the real task is a paired upgrade.
It then makes the change the message asks for, adds pydantic-settings to the requirements and imports BaseSettings from pydantic_settings, and immediately tests the thing that matters: does the application's own configuration still load. main.py builds its settings with Config(**unflatten_dict(yaml.safe_load(stream))) from config.yaml, so the agent runs exactly that against the file in the repository. Under the pinned 1.10.14 it loads. Under Pydantic 2 with only the import moved, the classes define, with a deprecation warning for each inner Config class and each use of Extra, and then loading fails with 2 validation errors for Config: doods.detectors.2.labelFile is Field required, and so is mqtt.
Nothing about settings sources caused that. Pydantic 2 changed what Optional[X] means when no default is written: the value may be None, but it must be supplied. Version 1 quietly defaulted such fields to None. config.py has three of them, labelFile: Optional[str] on the detector class, api: Optional[MqttApiConfig] and mqtt: Optional[MqttConfig], and the shipped config.yaml has a third detector with no label file and no mqtt section. The agent finds every annotation of that shape in the settings and request models, adds = None where version 1 behaviour was relying on it, and reruns the load. With those three defaults added, the same file loads under Pydantic 2 and yields the same values as before.
After that it clears the warnings without changing behaviour: each inner class Config becomes a model_config = SettingsConfigDict(...) with the same env_prefix, and Extra.ignore becomes the literal 'ignore'. It checks the prefixes still work by setting an environment variable such as SERVER_PORT and confirming the settings object picks it up on both versions. The request models in odrpc.py use pydantic.dataclasses, which still exists in version 2, so the agent leaves them and says it did.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "This project fails with \"pydantic.errors.PydanticImportError: BaseSettings has been moved to the pydantic-settings package\". First read the dependency pins and report whether any pinned package (a web framework, for example) declares a pydantic version below 2; if so, name it and the minimum version of it that accepts Pydantic 2, and upgrade the two together. Add pydantic-settings and import BaseSettings from pydantic_settings. Then find how the application builds its settings object at start-up and run that exact code against every sample or default config file in the repository, once on the currently pinned pydantic and once on Pydantic 2, and compare the loaded values. Fix what differs: in particular, find every field annotated Optional[...] with no default in settings and request models, since Pydantic 2 treats those as required, and add an explicit None default where the old behaviour relied on it. Convert inner Config classes to model_config with the same env_prefix and extra behaviour, and replace the Extra enum with literal values. Verify one environment-variable override per prefix still takes effect. Do not rename settings, environment variables or config keys, and do not change validation rules beyond what is needed to keep existing config files loading. Open a pull request showing the load result before and after and listing each field whose default you made explicit.",
"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 edits the settings module and the requirements file. Its description shows three loads of the repository's own config file: on the old pin, on Pydantic 2 with only the import moved, including the validation errors that step produces, and on Pydantic 2 after the fix. It lists each field that gained an explicit None default, three in doods2, and each Config class converted, with the prefix it carries. If a framework pin had to move for the upgrade to install, that change is called out at the top with the version constraint that forced it.
A reviewer confirms that no environment variable name or config key changed, since those are the interface operators depend on, and that every newly defaulted field was optional in practice before. They also check the framework upgrade separately; it is usually the larger risk, and the agent's note about it is a prompt to run the service's own tests or a smoke start before release, not a claim that the application was exercised end to end.
Run it on every start-up error in a deployed service
This failure happens at import time, so the service never comes up and the evidence is a crash log, usually in an error tracker or a container platform's event stream. Most of those systems sign their own webhook deliveries and cannot add the Authorization: Bearer header a Rush webhook trigger needs. Put a handler on your server in between: it receives the alert, keeps the ones whose message contains PydanticImportError, and posts the traceback to the trigger's URL with the trigger's secret.
A crash-looping service reports the same error many times. Have the handler send an Idempotency-Key header to the trigger's URL built from the service name and the error text, so repeats of one fire are recognised and start nothing new, and keep the automation's max runs per hour low.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
The second failure only appears when real configuration meets the new library, and that is a comparison across two installed versions. In a sandbox the agent builds one environment with the old pin and one with Pydantic 2, runs the application's own loading code in both against the repository's config files, and compares the values field by field. Both transcripts stay with the session. On a laptop this is the step people skip, because the import error going away feels like the fix.
The alternative path to finding it is production. A settings class that defines without error and then rejects the operator's config file fails at start-up on deploy, with a validation message about a field nobody touched. Getting that message in a pull request description, next to the three-line change that resolves it, is a much cheaper place to read it.
Frequently asked questions
Is installing pydantic-settings and changing the import enough?
It makes the import error go away. Whether the application then starts depends on your models: Pydantic 2 requires a value for Optional[...] fields that have no default, where version 1 filled in None. In doods2 the shipped config file fails validation on two such fields until explicit defaults are added.
Do I have to rewrite the inner Config classes?
Not immediately. Class-based config still works in Pydantic 2 and prints a deprecation warning that says it will be removed in version 3. The agent converts them to model_config in the same pull request because the change is mechanical and it can verify the environment prefixes still apply.
Why can't I install Pydantic 2 next to my FastAPI version?
Older FastAPI releases declare an upper bound on pydantic. FastAPI 0.70.1, for instance, requires a version below 2.0.0, so the resolver reports the requirements as unsatisfiable. The agent reads the pins first and upgrades the pair together.
Will my environment variables keep working?
Yes, when the prefix is carried over. The agent sets one variable per prefix, such as SERVER_PORT, and checks the loaded value on both the old and the new version. It does not rename any variable or key.