Delete node_modules and lock file, then reinstall

Run: rm -rf node_modules package-lock.json && npm install. This regenerates a clean lock file that matches your actual code. If npm install errors out with peer dependency conflicts, you have your first real problem to fix. Read the error and either pin a version or remove the conflicting package.

Run npm run build locally before pushing

Cursor's preview uses the dev server, which is more permissive than the production build. Run npm run build (or pnpm build / yarn build) locally. If it fails locally, it will fail in CI. Read the error in your terminal, which is more readable than the deploy log.

Check for 'use client' on files that import server-only code

If a file is marked 'use client' but imports something that uses Node APIs (fs, crypto, server-only DB clients), the build fails. Look at the build log for 'Module not found' or 'A Node.js API is used... in a client component'. The fix is to either remove 'use client' from the file or move the server logic to a separate file.

Verify environment variables on the deploy platform

Cursor uses a .env.local file that is not committed to git, so your deployed app does not have the env vars. Add every variable from .env.local to your Vercel or Netlify project settings, both for Preview and Production scopes. Forgetting NEXT_PUBLIC_ vars is the most common miss.

Look for hardcoded paths and absolute URLs

Cursor's agent sometimes hardcodes paths like '/Users/yourname/...' in import statements or fetch URLs. Search the codebase for any path that includes your username or a localhost URL. Replace with relative imports or environment variables.

Cursor

How to Fix Cursor-Built Apps That Will Not Deploy

Cursor builds run fine locally and the editor shows no errors, but deploys to Vercel or Netlify fail. The real causes and the fixes.

TL;DR

Cursor-built apps fail to deploy because the AI agent often skips package.json updates, leaves dev-only imports in production code, or generates Tailwind config that does not match the build pipeline. Fix the package.json first, then env vars, then check for client/server boundary issues.

What is actually happening

Cursor's agent installs packages with npm install but does not always update package.json correctly. It also assumes 'use client' and 'use server' directives are placed correctly, which it often gets wrong on edge cases. The result: builds that pass locally because dependencies are cached, but fail in CI because the lock file is wrong.

The fix, in order

Try these in sequence. Most apps are fixed by the first or second step.

1
Delete node_modules and lock file, then reinstall
Run: rm -rf node_modules package-lock.json && npm install. This regenerates a clean lock file that matches your actual code. If npm install errors out with peer dependency conflicts, you have your first real problem to fix. Read the error and either pin a version or remove the conflicting package.
2
Run npm run build locally before pushing
Cursor's preview uses the dev server, which is more permissive than the production build. Run npm run build (or pnpm build / yarn build) locally. If it fails locally, it will fail in CI. Read the error in your terminal, which is more readable than the deploy log.
3
Check for 'use client' on files that import server-only code
If a file is marked 'use client' but imports something that uses Node APIs (fs, crypto, server-only DB clients), the build fails. Look at the build log for 'Module not found' or 'A Node.js API is used... in a client component'. The fix is to either remove 'use client' from the file or move the server logic to a separate file.
4
Verify environment variables on the deploy platform
Cursor uses a .env.local file that is not committed to git, so your deployed app does not have the env vars. Add every variable from .env.local to your Vercel or Netlify project settings, both for Preview and Production scopes. Forgetting NEXT_PUBLIC_ vars is the most common miss.
5
Look for hardcoded paths and absolute URLs
Cursor's agent sometimes hardcodes paths like '/Users/yourname/...' in import statements or fetch URLs. Search the codebase for any path that includes your username or a localhost URL. Replace with relative imports or environment variables.

When to stop debugging and get help

If the build keeps failing on something cryptic and you cannot reproduce it locally, the issue is usually a misconfigured tsconfig, next.config, or vercel.json. These config files are easy to mess up and easy for an experienced engineer to fix quickly.

Stuck after trying these?

We do a $100 Quick Audit that pinpoints exactly what is wrong, why, and what it will take to fix. No sales call gating, no fluff.

Start a $100 Audit

Related fixes

Not sure exactly what is broken? Run a free scan and get a diagnosis in under 2 minutes.