Troubleshooting

Most deploy failures are a permission or a setting at a provider, not a problem with your app. The log says which, and running the deploy again picks up where it stopped.

A failed deploy's page opens with What happened: the likely cause in plain words and the steps that fix it. When the fault is in the app's own code, it also has a fix request to paste into the AI tool that wrote the app (Cursor, Lovable, Bolt, v0…), with the build's error lines included.

The app didn't build

The build failed on Vercel (Command "npm run build" exited with 1). The build said:
  Could not resolve "./pages/dashboard/Knowledge" from "src/App.jsx"

Launchpad waits for the host's build and fails the deploy when the build fails, with the lines from the build log that say why. The usual causes:

• A file the code imports isn't in the repository. It was never committed, or its name differs only in capital letters (Knowledge.jsx against knowledge.jsx). Mac and Windows ignore the difference; the Linux build server doesn't.
• A package isn't in package.json. It's installed on your computer, so it works there. Run npm install <package> and commit package.json and the lockfile.
• A type or lint error. npm run build on your computer shows the same error with its file and line.

Fix it and push: the push deploys again by itself.

Cloudflare: authentication error

Cloudflare: look for bucket my-app-uploads failed (HTTP 403): "Authentication error"

The token saved in Connections has no R2 permission on this account, or the account id belongs to a different account.

1. In Cloudflare, My Profile → API tokens, edit the token.
2. Add Workers R2 Storage → Edit and Account API Tokens → Edit, and include the account under Account Resources.
3. Check CLOUDFLARE_ACCOUNT_ID is the id from the account's home page, not a zone id.

The console's Cloudflare button creates a token with the right permissions already ticked.

Cloudflare R2 isn't turned on

Open R2 Object Storage once in the Cloudflare dashboard and turn it on. The free tier is enough, but Cloudflare asks for a payment method. Or turn file storage off for this app and deploy.

Supabase's free plan allows 2 active projects

Supabase's free plan allows two at a time. Either:

• press Move to Neon on the project page, which switches the database and deploys again (offered when nothing else needs Supabase and no Supabase project was created yet);
• pause a Supabase project you aren't using; or
• upgrade the Supabase organization.

New apps default to Neon, whose free plan allows a hundred projects.

The database is still starting

A new Postgres project takes a few minutes. The deploy says so and stops; deploy again in a few minutes and it continues from there.

The app is live but the page says "not configured"

The app is running without the variables it expects, usually because:

• a variable was added after the last deploy: deploy again, as a running app keeps the values it started with;
• the name doesn't match what the code reads;
• the part's secrets list leaves it out.

The deploy's log lists every variable it injected.

Vercel shows a sign-in page instead of my app

Team projects on Vercel protect their *.vercel.app address by default, so only signed-in team members can see them. Add your custom domain, or turn it off in the project's Deployment Protection settings.

Email isn't arriving

Resend won't send until the domain's DNS records are verified. Check:

• the DKIM, SPF and DMARC records from the deploy's Still to do list are in place;
• Resend's dashboard shows the domain as verified;
• if sign-in emails are the problem, that the email service is on, so they go through your domain rather than Supabase's shared sender.

See Email that reaches the inbox.

A domain stays "pending"

The DNS record hasn't propagated, or it's proxied. Records must be DNS-only so the certificate can be issued. Check the record matches the deploy's output exactly, then wait a few minutes.

The deploy failed and the message isn't clear

• The log holds the provider's own words, with keys scrubbed out.
• Run it again. Most failures are a transient provider error or a permission you've since fixed.
• If a step failed partway, nothing is duplicated: see How a deploy works.

The app was fine and now it isn't

A deploy that succeeded can still leave the live app broken — a request path that only fails with real data, an environment variable that was right in development and wrong in production. Two things help, both on the project's Logs and versions page (linked from Production on the project page).

Read what the app is saying. The page shows the app's own runtime logs: the requests it served, their status codes, and anything your code printed or threw. Vercel keeps these for a short window, so a quiet app often has none — open the app, then reload the page. Errors your code reports to Sentry appear under Errors on the project page instead, which keeps them for much longer.

Put the last good version back. The same page lists the recent production versions, newest first, each with its commit message. "Roll back to this" points your domain at a version that already built and ran. Nothing is rebuilt and nothing is deleted, so it takes effect in seconds and the version you replaced stays in the list — you can roll forward again just as easily.

A rollback doesn't change your code. The next push deploys whatever is on your branch, so fix the cause as well, or the next deploy brings the problem back.

Apps hosted on Cloudflare Pages or on your own server keep their logs and versions there, so this page only covers apps on Vercel.

Still stuck

Email hello@axonscape.com with the project's name and roughly when the deploy ran, and we'll look at the log. For anything security-related, use security@axonscape.com.