What the agent does
Mongoose 6 moved to version 4 of the MongoDB Node.js driver, which rejects connection options it does not know. useCreateIndex and useFindAndModify were Mongoose 5 switches for silencing deprecation warnings. In Mongoose 6 the behaviour they selected is the only behaviour, the options are gone, and passing one fails with MongoParseError: option usecreateindex is not supported. With several, the message lists them in lower case, joined by commas. The error is raised while the options are parsed, before any connection is attempted, so it appears even when the database is healthy.
yasser-mas/nodejs-user-management, a TypeScript user and permission service, shows how an app ends up here without anyone choosing to upgrade. Its package.json declares "mongoose": ">=5.7.5", a range with no upper bound. The committed lockfile still holds 5.10.14, so a plain npm install works. Regenerate the lockfile, run npm update, or install without it, and the range resolves to the newest major. source/db.ts then passes useNewUrlParser, useCreateIndex: true, useUnifiedTopology: true and poolSize to connect. On Mongoose 6, 7 and 8 the result is options usecreateindex, poolsize are not supported. On Mongoose 9 all four are named.
The agent installs the version the range resolves to and runs the connection code, and it finds that the title's error is the second one. The constructor in source/db.ts calls this.db.set('useFindAndModify', false) before it calls connect, and current Mongoose throws SetOptionError there: "useFindAndModify" is not a valid option to set. A fix that only edits the options object would leave the app crashing one line earlier. The agent removes the set call and the three use* options, and renames poolSize to maxPoolSize, which is what the driver calls it now. It also notes that nothing awaits or catches the promise connect returns, so the failure reaches the process as an unhandled rejection, and adds the handling.
Then it checks the edges of the upgrade. @types/mongoose is declared with the same open range, but Mongoose has shipped its own type definitions since late in version 5, and the old package conflicts with them, so the agent removes it and runs tsc. The Dockerfile starts from node:8-alpine and docker-compose.yaml runs the app on node:12.16.2-stretch-slim, while Mongoose 8 declares Node 16.20.1 or later and Mongoose 9 declares 20.19 or later, so the images have to move with the dependency or the range needs an upper bound. Because parsing happens before connecting, the agent can confirm the fix with no database: the rejection changes from MongoParseError to a server selection error for an address where nothing listens.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "This app fails at startup with \"MongoParseError: options usecreateindex, usefindandmodify are not supported\" (the list of options may differ). Read package.json and the lockfile and report the declared mongoose range, the locked version, and the version the range resolves to today. Install that version in a scratch copy and run the connection code against an address where no database listens, with a short server selection timeout, and record every error in the order it appears, including errors thrown before connect is called, such as mongoose.set() with an option that no longer exists. Find every place that passes options to mongoose.connect, mongoose.createConnection or mongoose.set. Remove useNewUrlParser, useUnifiedTopology, useCreateIndex and useFindAndModify; rename options the driver renamed (poolSize to maxPoolSize) and report any others it rejects. Make sure the promise returned by connect is awaited or has a catch that logs the error and exits non-zero. Check the rest of the Mongoose usage against the migration guides for each major version you cross and list what else must change: callbacks passed to queries or save, remove(), count(), update(), strictQuery. Remove @types/mongoose if the installed mongoose ships its own types, and run the TypeScript build. Compare the Node versions in the Dockerfile, compose file and CI with the engines field of the mongoose version you installed. Either bring them in line or cap the mongoose range, and say which you chose and why. Update the lockfile. Open a pull request with the errors before, the output after, and the list of remaining risks you could not test without a database.",
"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 connection module, package.json, the lockfile and, where the Node version had to move, the Dockerfile and compose file. The description gives the three versions that matter, declared, locked and resolved, then the errors in the order the old code produced them on the new version, then the output of the same script after the change. A separate list covers Mongoose calls elsewhere in the code that the newer majors changed, each with its file and line and whether the agent changed it.
A reviewer starts with that list, because the connection options are the part that fails loudly and the rest fails only when a route is called. Query callbacks, for example, were removed in Mongoose 7, and a model method that still passes one raises at request time. They check the dependency range: an open >= range is what caused the surprise, and the pull request should leave a caret range on the major the agent tested. The agent states plainly that it verified option parsing and the TypeScript build, and that no query ran against a real database in the session unless the description shows one.
Run it on every failed deploy
This error tends to appear in a deploy log, minutes after a build that regenerated the lockfile. Add an automation to the Project with a webhook trigger, and have your deploy pipeline's failure step call the trigger's URL with Authorization: Bearer and the trigger's secret, posting the tail of the log as the body. The log, up to 64 KB, is added after the prompt as event text, and the prompt tells the agent to find the failing dependency and open a fix. Send an Idempotency-Key header made from the deploy id to the trigger's URL so a retried hook starts nothing new.
If your builds run in GitHub Actions, a github trigger on workflow_run.failure does the same with no handler to write. Either way, set the automation's max runs per hour to a small number, since one bad lockfile fails every deploy until it is fixed.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
The useful question is not which options to delete; any migration guide answers that. It is what this codebase does on the version its range now resolves to, and the only way to know is to install that version and run the code. The agent does so in a sandbox, without touching your working lockfile, and reads the errors in the order they occur. That is how it finds a set call that fails before the documented error, and a Node image too old for the release that was installed. Each command and its output are kept in the session.
It can also try more than one target. Crossing from Mongoose 5 to 9 in a single step is four majors of breaking changes, and stopping at 6 may be the better first move. The run can install each candidate, report what breaks on each, and let you choose with the evidence in front of you.
Frequently asked questions
Do I need a replacement for useCreateIndex or useFindAndModify?
No. Mongoose 6 and later always behave as if useNewUrlParser, useUnifiedTopology and useCreateIndex were true and useFindAndModify were false. Delete the options and the behaviour you asked for stays.
I removed the options and now get "useFindAndModify is not a valid option to set". What is that?
A second copy of the same setting. Older code often called mongoose.set('useFindAndModify', false) as well as, or instead of, passing the option to connect. Current Mongoose throws on that call too. Remove it.
Why did this start without anyone upgrading Mongoose?
Check the version range in package.json. A range such as >=5.7.5, * or latest accepts every future major, so the next time the lockfile is rebuilt the app receives a release with breaking changes. The agent reports the range and proposes a caret range on the version it tested.
Is poolSize still supported?
Under another name. The driver calls it maxPoolSize now, and poolSize is rejected in the same error as the removed flags. The agent renames it and keeps your value.
Can the agent test against a real database?
It can test everything up to the connection with none, because option errors are raised before any network call. For queries it needs a MongoDB the sandbox can reach. Tell it in the prompt where a disposable test database is, or ask it to install MongoDB in the sandbox and run your test suite there.