# Fix Deprecated Zod 4 APIs in a TypeScript API

Yes. An agent finds each deprecated Zod call from the installed typings, replaces it without changing output, reruns typecheck and tests and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/fix-deprecated-apis/zod/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts from the versions on disk, since a deprecation is a note in one release's typings and not a general fact. In a TypeScript API like w3cj/hono-open-api-starter, `package.json` asks for `zod` `^4.0.14` and `pnpm-lock.yaml` resolves 4.0.14, beside `@hono/zod-openapi` 1.0.2, `drizzle-zod` 0.8.2 and `stoker` 2.0.1. The README says the starter was moved to Zod 4 after its video was recorded and links the commit. That move left Zod 3 idioms that still compile. Zod is used in a handful of places: `src/env.ts` validates the environment, `src/db/schema.ts` derives insert and select schemas from the Drizzle table, `src/lib/zod-utils.ts` holds a cast helper, and `src/routes/tasks/tasks.test.ts` asserts on issue codes and messages.

It takes a baseline, and the baseline is not clean. `pnpm typecheck` passes. `pnpm test` passes its one file after `beforeAll` runs `pnpm drizzle-kit push` against the `file:test.db` named in `.env.test`. `pnpm lint` fails before any change, on an unused `z` import at the top of `src/db/schema.ts`. And nothing in the project can see a deprecation: `eslint.config.mjs` calls `@antfu/eslint-config` with `typescript: true` and no `tsconfigPath`, so no type-aware rule runs, and there is no workflow under `.github`. The agent makes the compiler's knowledge visible for one pass by linting `src` with a throwaway config that sets `tsconfigPath` and turns on `ts/no-deprecated`. That reports five uses in three files, each with the note from Zod's own typings: `.url()` on a string, `ZodIssueCode` twice, `flatten` on an error, and `ZodTypeAny`.

Each replacement is small, and the agent checks that it changes nothing a caller can observe. `z.string().url()` becomes `z.url()`, and the agent confirms the development value `file:dev.db` still parses. `z.ZodIssueCode.invalid_type` becomes the string `"invalid_type"` in `env.ts`, and in the test `ZodIssueCode.too_small` becomes `"too_small"` and its import goes. `ZodTypeAny` in the cast helper becomes `ZodType`. The `flatten` call takes a decision: the deprecation note points to `z.treeifyError`, which returns a different shape, and this code prints `fieldErrors` for a person reading a failed boot. The agent uses `z.flattenError(error).fieldErrors`, which exists in 4.0.14 and keeps the shape, then starts the app with a bad `LOG_LEVEL` and a bad `DATABASE_URL` before and after and compares the printed block, which comes out identical.

Then it draws the line around the job. `superRefine` in `env.ts` carries no deprecation note in this version's typings, so it stays. The `toZodV4SchemaTyped` cast and the `@ts-expect-error` on `patchTasksSchema` exist because `drizzle-zod`, the `z` that `@hono/zod-openapi` exports and `zod/v4` do not agree on types at these versions; removing them means upgrading those packages, which is a different pull request. `src/lib/constants.ts` hard-codes Zod's message text, such as `Invalid input: expected number, received NaN`, for the tests to compare against, which will break on a wording change upstream; the agent notes it. It reruns `pnpm typecheck` and `pnpm test`, runs the deprecation lint again to see zero reports, and removes the unused import only if the prompt allows, since it predates the task.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Remove deprecated Zod API usage from this TypeScript API. Read package.json, pnpm-lock.yaml (resolved zod, @hono/zod-openapi, drizzle-zod and stoker versions), eslint.config.mjs, tsconfig.json, vitest.config.ts, .env.example, .env.test, the README, src/env.ts, src/db/schema.ts, src/lib/zod-utils.ts, src/lib/constants.ts and everything under src/routes first. Run pnpm install --frozen-lockfile, pnpm typecheck, pnpm lint and pnpm test before changing anything and record the result of each; a failure that exists before your change is reported, not hidden. Find deprecated uses from the installed typings, not from memory: lint src once with a temporary type-aware ESLint config that enables ts/no-deprecated, list every report with file, line and the deprecation note, and do not commit that config. Replace each use with the API the note or Zod's documentation names, keeping behaviour identical: where a replacement would change output, such as the shape printed for an invalid environment, pick the one that keeps it and show the output before and after. Do not upgrade any package, do not remove the toZodV4SchemaTyped cast or the @ts-expect-error in src/db/schema.ts, and do not rewrite code that has no deprecation note. You may remove the unused import that makes pnpm lint fail, in its own commit. Rerun typecheck, tests and the deprecation lint, and open a pull request with a table of each deprecated use and its replacement, the command output before and after, and a list of what you saw and left alone with the reason.",
  "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 three files by a few lines each: `src/env.ts`, `src/lib/zod-utils.ts` and `src/routes/tasks/tasks.test.ts`, plus a one-line commit to `src/db/schema.ts` if the unused import was in scope. No dependency moves and the lockfile is untouched. The description opens with the table of deprecated uses, giving file and line, the text of the note the typings carry, and the replacement chosen. The `flatten` row has a sentence of its own, because the agent did not follow the note's suggestion and explains why the output had to stay the same.

Under the table are the commands. Typecheck and tests are shown before and after. The lint is shown with its pre-existing error, and the temporary deprecation lint is shown going from five reports to none, with the config it used pasted in the description and not committed. A last section lists what was seen and left: the cast helper and the `@ts-expect-error`, `superRefine`, the hard-coded message strings, and the fact that the repository has no CI workflow to run any of this on the next pull request.

A reviewer checks that the environment validation still fails closed: an invalid variable still prints the same block and exits with code 1. They check the test now compares against a string literal that is the real issue code, not a typo that happens to match nothing. And they decide whether to keep the deprecation rule on for good, knowing what it brings: with `tsconfigPath` set, the preset enables its other typed rules too, and in the agent's check `ts/strict-boolean-expressions` fired on `src/env.ts`.

## Run it on every first of the month

Deprecations arrive with minor releases, and a caret range like `^4.0.14` takes them the next time the lockfile is refreshed. Create an automation in the Project that holds the repository with a `schedule` trigger whose `cron` is `0 9 1 * *` in your `timezone`, and a prompt that says: lint `src` with `ts/no-deprecated` enabled; if it reports nothing, end with one line; otherwise replace each use as its note says, keep output identical, run typecheck and tests and open a pull request. It runs as the member who last changed the automation, and turning it off pauses it without losing the prompt.

## Why run it on Rush?

The reliable list of deprecated calls is in `node_modules`, in the typings of the exact version the lockfile resolves, and reading it needs an install and a type-aware pass over the source. Sent from a terminal as one request, it happens in the agent's sandbox on a fresh clone, and the list in the pull request matches what your build resolves and not what a migration guide said about a different minor.

The second half of the job is proving that nothing changed, and that is commands too: typecheck, the test file that pushes a schema to a scratch SQLite database, and the application booted with bad variables to compare its output. All of it is kept in the session's transcript at `GET /o/{org}/sessions/{id}/messages`, each command with its output. The reviewer does not have to trust that `z.flattenError` prints the same block as the old method; both printouts are there.

## Frequently asked questions

### How does the agent know which Zod calls are deprecated?

From the `@deprecated` notes in the typings of the version your lockfile resolves, surfaced by a type-aware lint rule. For Zod 4.0.14 that includes `.url()` on a string, `ZodIssueCode`, `ZodTypeAny` and `flatten` on an error. A method with no note in your version is left alone, even if a newer release deprecates it.

### Is error.flatten() replaced by z.treeifyError?

That is what the note suggests, but the two return different shapes. Where code reads `fieldErrors`, as this project's environment check does, `z.flattenError(error)` is the function that keeps the shape. The agent picks by what the surrounding code consumes and shows the output before and after.

### Will this upgrade Zod or related packages?

No. The request forbids version changes, and the lockfile is not touched. Workarounds that exist because of how `drizzle-zod` and `@hono/zod-openapi` type their schemas stay until those packages are upgraded, and the pull request lists them so that job can be scheduled.

## More Zod jobs

- [Upgrade Zod 3 to Zod 4 in a React App](https://getrush.ai/run/upgrade-zod/zod/)
- [Validate Environment Variables With Zod in a Next.js App](https://getrush.ai/run/add-env-validation/zod/)

## The same job on other stacks

- [Fix Deprecations in an Ember App](https://getrush.ai/run/fix-deprecated-apis/ember/)
- [Replace Deprecated Flutter APIs Across an App and Make the Analyzer Catch the Next Ones](https://getrush.ai/run/fix-deprecated-apis/flutter/)
- [Fix Deprecated APIs in a LangChain.js App](https://getrush.ai/run/fix-deprecated-apis/langchain/)

## More jobs like this: Hand off a long task

- [Fix "AttributeError: 'EntryPoints' object has no attribute 'get'" on Python 3.12](https://getrush.ai/run/fix-entrypoints-object-has-no-attribute-get/importlib-metadata/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
