Bolt.new deploy to Netlify failed? How to read the log

When a Bolt.new project fails to publish to Netlify, the cause is almost always written in the build output, a few lines above the final "failed" message. Find the first real error (a missing module, a TypeScript error, a wrong output folder, a Node version mismatch), fix that one thing, and publish again. The last line, such as Build script returned non-zero exit code: 2, only tells you that something earlier went wrong.

This guide shows where the output lives in Bolt and in Netlify, how to read it, the causes behind most failed deploys, and a few checks that stop the same failure from coming back.

Where do I find the build log?

First, know which route you use. Some people publish with Bolt's own Publish button after choosing Netlify as the hosting provider in Domains & Hosting. Others connect the GitHub repository to a Netlify site, so Netlify builds every commit itself. The log lives in a different place for each.

1. Inside Bolt. Open Code view (the </> icon), expand the bottom panel and open the Publish Output tab. Bolt writes the output of every publish there. The Bolt tab next to it shows what happens while the preview runs.
2. Inside Netlify. Open the site in the Netlify dashboard, go to Deploys and click the failed deploy. The deploy log is the full record of the build, including the error. For sites that Netlify builds from GitHub, this is the log that matters.

If Bolt itself cannot publish, Bolt's publishing troubleshooting page suggests a manual route: run npm run build in the Bolt terminal, download the project and use Netlify's drag-and-drop deploy for the output folder. That also tells you whether the problem is the build or the connection.

How do I read a failed build log?

Start at the end, where the summary and exit code are, then move up until you find the first line that starts with error, Error:, ERR! or Module not found. Copy that line and the five to ten lines around it. That block is what you paste into Bolt or send to a developer. Lines like Command failed with exit code 1 only repeat the verdict.

What usually causes a Bolt.new deploy to fail on Netlify?

Case-sensitive file names

Netlify's build file system is case sensitive, so Header.tsx and header.tsx are different files. If the log says a module can't be resolved and the file clearly exists, compare the capital letters in the import with the real file name.

The output folder

Vite projects, which most Bolt web projects are, build into dist. If the publish directory points to build or the project root, the build passes and the site is empty or missing. In Netlify the setting is under the project's build settings; in a netlify.toml file it looks like this:

[build]
  command = "npm run build"
  publish = "dist"

The Node version

Bolt runs your project in the browser, while a build on Netlify uses the Node version pinned to your Netlify site. If a package needs a newer Node, the build fails with syntax or engine errors. Netlify's dependency documentation lets you set a NODE_VERSION environment variable or add a .nvmrc or .node-version file with a major version such as 22. Use the same major version you test with locally.

Dependency conflicts

When the log shows ERESOLVE, two packages want different versions of a shared dependency. The clean fix is to update or downgrade one of them so they agree. As a stopgap, Netlify documents an NPM_FLAGS environment variable set to --legacy-peer-deps. Our guide to npm dependency errors in Bolt.new covers this in more depth.

Missing environment variables

Variables that start with VITE_ are baked into the JavaScript at build time. When Netlify does the build, it only sees the variables set in its own environment variables, not your Bolt .env file (which shouldn't be in GitHub anyway). The build can pass and the live app then breaks with errors like supabaseUrl is required. Add the variables in Netlify, then trigger a new deploy, because changing a variable doesn't rebuild anything on its own. The rules for what can go there are in our guide to environment variables in Bolt.new.

Routes that 404 after a refresh

A React single-page app has one real file, index.html. Netlify needs a rule that sends every path to it. Create public/_redirects with:

/*    /index.html   200

What can Netlify not host from a Bolt project?

Bolt's documentation is direct about this: Netlify hosting through Bolt is for sites that run entirely in the browser. It doesn't host a database or a traditional backend. If your project relies on Bolt Database, server functions or Bolt's authentication, publishing to Bolt hosting may be the right choice, or the backend needs to live somewhere else, such as a Supabase project you control, while Netlify serves the front end.

Two other limits worth knowing:

• Bolt won't publish projects over 100MB in total. Large images and videos are the usual reason; move them to external storage.
• A duplicated or forked project loses its Netlify connection, and reconnecting creates a new Netlify site, so point your custom domain at the new one.

How do I confirm the fix worked?

1. Run npm run build in the Bolt terminal first. If it fails there, it will fail on Netlify too.
2. Publish, then open the Netlify deploy log and check that it ends with a published deploy and no errors above it.
3. Open the live URL in a private window, reload a page that isn't the home page, and check the browser console for red errors.
4. Test the one feature that depends on environment variables, usually sign-in.

How do I stop it from happening again?

• Keep one netlify.toml in the project with the build command, publish folder and Node version, so the settings live with the code.
• Run npm run build before every publish, not only when something looks wrong.
• Connect the project to GitHub, so each deploy maps to a commit you can roll back to.
• Write down which environment variables the app needs and where each one is set.

If you're still choosing a host, our Netlify vs Vercel comparison explains the trade-offs.

Quick answers

Why does it work in the Bolt preview but fail on Netlify? The preview and Netlify run different environments: different Node versions, a case-sensitive file system and a stricter production build. The log tells you which difference matters.

Should I keep clicking Publish until it works? No. Without a change, the same build fails the same way. Read the first error, fix it, then publish.

Can I deploy to Netlify without connecting my Bolt account? Yes. Build in Bolt, download the project and drag the output folder into Netlify's manual deploy page.

Still failing after the obvious fixes?

If the log points somewhere you can't follow, start with the free health check on your live URL. For a deeper look, our Bolt app rescue work starts with a code review and a fixed price for each fix before anything changes, and the maintenance plans keep deploys healthy afterwards. You can also send us the log and a person will reply within one business day.