AppsBolt

Bolt app works in the editor but the deploy fails

Your Bolt project runs fine inside Bolt, but the build fails on Netlify or another host. Most of the time it is a missing setting, a missing package or a missing environment variable.

  • Difficulty: Medium
  • Time: 20 to 60 minutes
  • Updated October 28, 2026

Symptoms

  • The deploy log ends with "Build failed"
  • The site deploys but shows a blank white page
  • Pages work from the home page but show 404 when you refresh them
  • Features that use an outside service stop working online

Why it happens

Bolt runs your app in its own environment inside the browser. A host like Netlify builds your app again from scratch on its own servers.

Anything that only existed inside Bolt is missing there. That can be secret keys, settings, or packages that were never saved to package.json. The host also needs to know which command builds the app and which folder to publish.

The good news: the build log almost always tells you which piece is missing.

Try this first

  1. Read the first error in the build log

    Open the failed deploy and scroll up to the first red line, not the last one. The first error is usually the real cause. The rest often follow from it.

  2. Check the build settings

    Most Bolt projects use Vite. For those, the build command is npm run build and the folder to publish is dist. Make sure your host uses the same values.

    Build command: npm run build
Publish directory: dist

  3. Add your environment variables

    Every key your app uses, like a Supabase address or an API key, must also be added in the host settings. In Vite apps, values the browser needs must start with VITE_.

    VITE_SUPABASE_URL=https://yourproject.supabase.co
VITE_SUPABASE_ANON_KEY=your-public-anon-key

  4. Fix 404 errors on refresh

    If pages load when you click around but show 404 when you refresh them, the host needs a rule that sends every address to index.html. On Netlify, create a file called _redirects inside the public folder with this line:

    /*    /index.html   200

  5. Install missing packages

    If the log says a module cannot be found, install it so it is saved in package.json. Then push the change and deploy again.

    npm install package-name

When to stop and call a person

Call a person if the errors mention types across many files, if the build runs out of memory, or if your app needs a server but your host only serves static files. Those are signs the project needs some restructuring, not just a setting.

Request a repair crew

Questions people ask

Why does it work in Bolt but not online?

Bolt keeps some things in its own environment. The host starts from nothing, so anything not saved in the project files is missing.

Can VITE_ variables hold secret keys?

No. Anything that starts with VITE_ ends up in the browser, where anyone can read it. Secret keys belong on a server or in a server function.