# Fix a Failed Vercel Deployment of an Astro Site

Yes. The failed deployment starts a run that reads the Vercel build log, reruns astro build in a sandbox and opens a pull request with the fix.

[Run this on Rush](https://cloud.getrush.ai/run/fix-vercel-build-failures/astro/), in a Project that has your repository.

## What the agent does

The run begins with the deployment event placed after the prompt as untrusted data. The agent takes the deployment id from it, reads that deployment's build log through the Vercel connection, and finds the first error rather than the last line, since `astro build` keeps printing page output after a content or type error and ends on a generic exit code. It then clones the repository at the commit Vercel built into its own cloud sandbox.

In a large Astro content site like `withastro/docs`, the agent reads `package.json` and finds `astro build` as the `build` script, Astro 7 with Starlight 0.42, and `"packageManager": "pnpm@11.1.2"` beside a `pnpm-lock.yaml`. It installs with pnpm, not npm, so the dependency tree matches the deployment. `.nvmrc` pins Node 24.14.1 while `.github/actions/install/action.yml` sets up 24.18.0, so the agent checks which major the Vercel project used before deciding a failure is a Node difference.

Most red Astro deployments in a site of this shape come from content, not code. `src/content.config.ts` defines the docs collection with a Zod schema (`i18nReady`, `githubURL`, a `deploy` type whose `logo` must be one of the keys in `src/data/logos`), so a page with a misspelled frontmatter field or a logo key that does not exist fails the whole build. `astro.config.ts` sets `trailingSlash: 'always'`, and `src/pages/open-graph/[...path].ts` renders an image per page with canvaskit unless `SKIP_OG` is set, which is the slowest part of the build and the first place a memory limit shows up.

Once the sandbox build fails on the same line as the Vercel log, the agent fixes the cause in the file the log names: the frontmatter of one `.mdx` page under `src/content/docs/`, an import in a component under `src/components/starlight/`, or the sidebar entry in `astro.sidebar.ts` that points at a page that was moved. It reruns `pnpm build`, then `pnpm run check` (which is `astro check`) and `pnpm run lint:slugcheck`, the same checks the repository's `ci.yml` runs on every pull request.

## Start it with one API call

`POST https://api.prix.dev/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "A Vercel deployment of this Astro site failed; the deployment event follows this prompt. Use the Vercel connection to read that deployment's build log and quote the first error line. Install with the package manager and lockfile the repository declares, reproduce the failure with the build script in the sandbox, and fix the cause in the file the log names. Confirm the build passes and that `astro check` passes, then open a pull request that quotes the failing log line, names the file and explains the fix. Do not set SKIP_OG or remove pages to make the build pass.",
  "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.prix.dev/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

What comes back is a pull request on its own branch whose description starts with the error line from the Vercel log, then the file and the cause, then the tail of the passing `pnpm build` from the sandbox. For a content failure the diff is usually a few lines of frontmatter in one page; a change to `astro.config.ts`, `src/content.config.ts` or a dependency version is called out on its own, because it changes every page of the site.

Vercel builds a preview for the branch, so the first check a reviewer opens is the one that was red. They confirm the preview deploys, open the page that broke, and read the fix to see it corrects the field the schema refused rather than loosening the schema with an `.optional()`. The session record has every command the agent ran and its output, so the reviewer can see the failing build before the fix and the passing one after it.

When the build passes in the sandbox at the failed commit, the run reports that instead of guessing. It lists what differs between the sandbox and the deployment, such as a Node major, a missing environment variable or a build that ran out of memory, and opens no pull request for a problem that lives in the Vercel project settings.

## Run it on every failed Vercel deployment

Add an automation to the Project with this prompt and a `webhook` trigger. Rush shows the trigger's URL and secret once; a call to that URL needs `Authorization: Bearer <secret>`, and its body, up to 64 KB, becomes the event text the agent reads. Vercel signs its own webhooks and does not add that header, so point Vercel's deployment-error webhook at a small function of yours that checks Vercel's signature and forwards the body to the trigger URL with the bearer secret.

Have that function send the Vercel deployment id as the `Idempotency-Key` header. A retried delivery of the same failure then maps to the run it already started instead of opening a second pull request. The function can just as well call `POST /o/{org}/sessions` with the event in `input` and wait for the key's `run.completed` webhook.

## Why run it on Rush?

Fixing a red Astro deployment by hand means opening the Vercel log, scrolling past thousands of rendered pages to the first error, checking out the commit, installing the right pnpm and Node, and waiting for a full build of every locale. A Rush run does each of those steps in its own sandbox and keeps the output of every command, so the build that failed and the build that passed are both on the record.

Content sites break often and in parallel: a translation pull request and a docs change can each fail their own deployment on the same afternoon. Each failure starts its own run on its own branch, none of them touches anyone's laptop, and a run that cannot reproduce the error says so instead of ending with a false done.

## Frequently asked questions

### Does it use pnpm or npm?

Whatever the repository declares. In `withastro/docs` that is `pnpm@11.1.2` in `packageManager` with a `pnpm-lock.yaml`, so the agent runs `pnpm install` and `pnpm build`. A site with only a `package-lock.json` gets `npm ci` and `npm run build`.

### How does the run read my Vercel build logs?

Through the Vercel MCP server, which reads build and runtime logs and inspects deployments. Connect it once with `POST /me/connections` and `"auth": {"mode": "oauth"}`, finish the sign-in in a browser, then name it in `connections` on the run or on the saved agent the automation uses.

### Will it relax my content schema to get the build through?

The prompt tells it to fix the cause in the file the log names, which for a frontmatter error is the page, not `src/content.config.ts`. If the schema itself is wrong, the change to it is called out separately in the pull request so a reviewer decides.

### My build generates Open Graph images and takes a long time. Is that a problem?

The sandbox runs the full build, including `src/pages/open-graph/[...path].ts`, because skipping it would hide the failure you are fixing. The prompt forbids setting `SKIP_OG` as a fix, so an image route that breaks is repaired, not switched off.