Works locally, breaks on Vercel
A practical fix and a copyable AI coding prompt. Replace bracketed placeholders with your project details.
1. Check the problem
90% of the time it's one of four things: a missing env var, a Node version mismatch, an Edge runtime running a Node-only API, or a serverless filesystem write. Check the Vercel function logs first, they'll tell you which.
2. Use the prompt
My app works locally but breaks on Vercel: [paste the error or behavior]. Walk the four usual causes in order, missing env var, Node version mismatch, Edge runtime using a Node API, and serverless filesystem writes. For each, tell me exactly what to check in my project and the Vercel logs, plus the fix.3. Verify the fix
Review the proposed diff, run the relevant checks and exercise the original failing flow before merging.
Continue in the related workflow chapter.