What the agent does
marshmallow 3 changed how every schema is called: load raises on invalid input and returns the data itself, where version 2 returned a result with .data and .errors. Code written for 2 breaks at each of those points, in an order that only running it reveals. The agent begins by recording a baseline. In a project like Netflix/bless, requirements.txt pins marshmallow==2.19.2 while setup.py lists a bare marshmallow, so anyone who installs the package without the requirements file already gets a newer major. The tests run with py.test tests, and the agent notes which of them fail before it touches anything; installed with a current cryptography, a handful here fail on a private function that package no longer has, and it sets those aside by name.
Then it installs marshmallow 3 and follows the failures. The first layer is two TypeErrors. Schema.__init__() got an unexpected keyword argument 'strict' comes from BlessUserSchema(strict=True) and BlessHostSchema(strict=True) in the two Lambda handlers; version 3 is always strict, so the argument is removed. Email.__init__() takes 1 positional argument but 2 were given comes from Email('Invalid email address.') in bless_request_user.py, where the message is now the keyword error.
Fixing those exposes the next layer: check_unknown_fields() got an unexpected keyword argument 'partial'. Version 3 passes extra keyword arguments to @validates_schema and @post_load methods, so each hook gains **kwargs. And schema.load(event).data in the handlers loses its .data, because load now returns what @post_load built. After those four kinds of edit, nine changed lines in four files, the suite is back to its baseline.
Passing tests are not the end of it, and the agent says what they do not cover. Both schemas carry a hand-written check_unknown_fields hook, and version 3 rejects unknown fields by default before that hook matters. The handlers return str(e) to the caller, and that string is different now: an extra field reads {'extra': ['Unknown field.']}. The tests assert only the error type, so the agent prints the old and new message for each validation case and puts the table in the pull request. It also checks one release ahead. On marshmallow 4 the same code fails with 'BlessUserSchema' object has no attribute 'context', because both schemas read validation options from self.context. The agent pins marshmallow>=3,<4 in setup.py and describes that follow-up without doing it.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Upgrade this project from marshmallow 2 to marshmallow 3. First install the currently pinned dependencies, run the test suite, and record the result as the baseline, listing any tests that already fail and why. Then install the newest marshmallow 3 release and run the tests again. Fix failures in the order they appear and keep a list of each kind of change with its error message: the strict argument, .data and .errors on load and dump results, positional arguments to validators and fields, missing and default renamed to load_default and dump_default, load_from and dump_to replaced by data_key, hook methods that need **kwargs, pass_many and pass_original signatures, and ValidationError arguments. Search for every Schema subclass and every load, dump, validate, loads and dumps call, including ones no test reaches, and fix those too. Version 3 raises on unknown fields by default: for each schema, decide from the existing code whether unknown input was rejected, ignored or passed through before, set Meta.unknown to keep that behaviour, and report it. If validation error messages are returned to callers or logged, show the message before and after for each validation rule. Update the pin in every manifest to allow 3.x and exclude 4. Finally, install marshmallow 4 in a separate environment, run the tests once, and report what would break next without fixing it. Open a pull request.",
"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 short and whose description explains each line. For bless it changes the two handler modules, the two schema modules, requirements.txt and setup.py. The description lists the four kinds of edit with the error that led to each, then the test result against the baseline, with the tests that were already failing named so nobody attributes them to this change.
The section a reviewer should spend time on is behaviour that tests did not pin: how unknown fields are handled now, and the before-and-after text of each validation message. If a client parses those messages, or an alert matches on them, this is where that surfaces. The agent proposes either accepting the new text or formatting e.messages back into the old shape, and implements whichever the request asked for.
The closing note is the marshmallow 4 preview: which attribute is gone, which schemas use it, and that the new pin keeps the project on 3.x until that work is done.
Run it on every failed CI run after a dependency bump
The usual way a team meets this upgrade is a red build: a lockfile refresh or an unpinned install pulls marshmallow 3 and the suite fails with the strict error. Add an automation to the repository's Project with a github trigger on workflow_run.failure and save the prompt above. The failed run's event is placed after the prompt as event text, so the agent starts from the job that failed. Runs from forks and from bot senders never fire the trigger, so a dependency bot's own pull request will not start it; a merge by a maintainer that then fails on the main branch will.
Keep the automation's max runs per hour low. A broken main branch can fail many workflows in a few minutes, and one run is enough to produce the fix.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
This upgrade fails in layers, and each layer hides the next. Nobody can list the edits from the changelog alone, because which ones apply depends on which features the schemas use. Working through it means install, run, read the first error, fix, run again, several times over. An agent in its own sandbox does that loop without tying up a developer's environment, and every test run with its output is kept in the session transcript, so the claim that the suite is back to baseline comes with the output that shows it.
The second environment matters too. Checking marshmallow 4 in a separate install, in the same run, turns a future surprise into a known item with a pin that prevents it. On a laptop that step is usually skipped because it means building another virtualenv for a result that changes nothing today.
Frequently asked questions
What replaces schema.load(data).data?
schema.load(data) on its own. In version 3 load returns the deserialized value directly and raises ValidationError when the input is invalid. The errors that used to be in .errors are on the exception as e.messages.
Do I still need strict=True?
No, and passing it is an error. Every schema in version 3 behaves as strict schemas did in version 2. Remove the argument from constructors and from class Meta.
Why do my post_load and validates_schema methods fail with an unexpected keyword argument?
Version 3 passes many and partial to decorated hook methods as keyword arguments. Add **kwargs to each hook's signature. Hooks that used pass_original=True keep receiving the original data as a positional argument.
Will marshmallow 3 reject input that version 2 accepted?
Yes, in one common case. Fields that are not declared on the schema were silently dropped in version 2 and raise a validation error by default in version 3. Set unknown = EXCLUDE in the schema's Meta to keep the old behaviour, or leave the default if rejecting them is what you want.
Should I go straight to marshmallow 4?
Do 3 first. It keeps deprecated features working that 4 removes, such as Schema.context, so you can fix the version 2 patterns and get a green suite before taking on the next set of removals. The agent reports what 4 would break as part of this job.
More marshmallow jobs
More jobs like this: Upgrade dependencies weekly
- Upgrade Mongoose 5 to the Current Major in an Express API (Mongoose)
- Upgrade an Express App to Node 24 (Express)
- Upgrade a NestJS App to Node 24 (NestJS)
- Upgrade a Node.js App to Node 24 (Node.js)
- Upgrade npm Dependencies in a Chrome Extension Project (Chrome Extension)