Fix Bolt.new 404 Errors After Deploying to Static Hosts

Your Bolt.new app works in preview, but subpages return 404 after deploying to Netlify, Vercel, or GitHub Pages. This happens because your static host does not know how to route a Single-Page Application (SPA). The fix is platform-specific: add a routing config file and redeploy. This guide walks through the diagnosis and fix for each platform.

Why does my Bolt.new app show 404 on subpages after deploying?

Bolt.new builds Single-Page Applications that rely on client-side routing. In preview, Bolt's dev server catches all requests and passes them to your app. Static hosts like Netlify serve files from disk. Without routing rules, a request to /about returns 404 because no physical file exists.

A Single-Page Application is one JavaScript bundle that lives at index.html. All routing happens in the browser, not the server. In Bolt's preview environment, the dev server intercepts every request -- whether it is /, /pricing, or /dashboard -- and feeds them all to index.html. Your React/Vue/Svelte app then parses the URL and renders the right page. This works perfectly in development.

Static hosting platforms like Netlify and Vercel replicate this in production, but require explicit configuration. Without it, the server sees /pricing and looks for a file or folder named /pricing. It does not find one, so it returns 404.

This is not a Bolt bug. It is how web hosting works. Every framework (Next.js, Nuxt, Angular) that builds an SPA faces the same issue. The solution is identical: tell your static host to send all requests to index.html. The homepage works by accident, because index.html exists. Every other route requires routing config.

How do you know if this is a build failure or a routing issue?

Check your Bolt.new build logs first. If the build succeeded but the homepage works and subpages fail, it is a routing issue, not a build failure. A true build failure would show a blank page or deployment error.

Open the deployment log in Netlify, Vercel, or GitHub. Look for error messages during the build step. If the build completed with no errors and the deployment succeeded, your app is deployed correctly. The issue is routing config, not code.

The telltale sign of a routing issue is this: the homepage (/) loads and works perfectly, but any link to /about, /contact, /dashboard, etc. returns 404. This is 100% a routing misconfiguration. The app is deployed; the host just does not know where to find subpages.

If you see a blank page everywhere, or a deployment error in the logs, that is a build failure. Debug that first: check if your environment variables are set in your deployment platform, or if you have a build error in your Bolt.new app (oversized prompt, missing dependencies, conflicting versions, etc.). Resolve the build error before adding routing config.

How to fix 404 errors on Netlify

Create a _redirects file in your Bolt.new project root with one line: /* /index.html 200. Commit it to git and redeploy.

Netlify's routing fix is a simple text file. Create a file named _redirects (no extension) in your project root, at the same level as your package.json or src folder:

/* /index.html 200

That is the complete configuration. The /* means "all requests." The /index.html means "point them here." The 200 means "do not throw a 404; silently serve the file."

Commit this file to git. When you redeploy Bolt.new to Netlify, it will pick up the _redirects file automatically. Every request now goes to index.html, and your SPA parses the URL from there. No more 404s on subpages.

Why does not Bolt.new or Netlify do this by default? Because not all static sites are SPAs. Some are plain HTML with separate pages per route. A _redirects file would break those. So the platform leaves routing to you, the developer.

If you are still hitting 404s after adding _redirects, check two things: first, the file is in your project root (same level as package.json, not inside a folder). Second, the file has no extension (not _redirects.txt). Then redeploy and wait 30 seconds. The error should clear.

How to fix 404 errors on Vercel

Create a vercel.json file in your project root with a rewrite rule. Point all routes to index.html and redeploy.

Vercel's config is a JSON file. Create vercel.json in your project root:

{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

The source pattern matches all requests. The destination sends them to index.html. Vercel interprets a successful rewrite as status 200 implicitly; no 404 is thrown.

Commit and redeploy. Vercel picks up the config automatically on the next deployment.

A note on the regex: (.*) matches any path. Some teams use simpler patterns like /:path* if their app uses a specific path prefix. For Bolt.new apps targeting root, (.*) works universally and requires no tweaking.

If you have other Vercel configuration (environment variables, build settings, database connections), add the rewrites object to your existing vercel.json. Do not replace the whole file. After deployment, test by visiting a subpage directly in the browser: go to /about or /contact. If it loads and renders your SPA, you are done. If it still 404s, clear your browser cache and try again.

How to fix 404 errors on GitHub Pages

GitHub Pages does not support routing rules. Use a 404.html file containing your SPA's index.html code. GitHub serves this on any 404, and your app router handles the rest.

GitHub Pages is different from Netlify and Vercel. It does not support _redirects or vercel.json. Instead, it has a documented workaround: name your catch-all file 404.html.

Create a file named 404.html in your project root and make it identical to your index.html:

<!DOCTYPE html>
<html>
  <head>
    <title>My Bolt App</title>
    <link rel="stylesheet" href="/styles.css">
  </head>
  <body>
    <div id="app"></div>
    <script src="/bundle.js"></script>
  </body>
</html>

When someone visits /about and GitHub Pages cannot find that file, it serves 404.html instead. Your JavaScript then reads the URL and renders the right page.

This approach sounds hacky because it is, but it works reliably. GitHub Pages reads your 404.html file for any missing route, and your SPA bootstrap runs every time. One caveat: your SPA's initial load is slightly slower (one extra file read for each subpage visit). For most applications, this is imperceptible.

Commit the 404.html file, push to GitHub, and redeploy. Test by visiting a subpage directly. The error should resolve.

Can you ask Bolt.new to generate the fix automatically?

Yes. Bolt.new's AI builder can suggest the right config file. Ask it directly in the chat: "I'm deploying to Netlify and getting 404 on subpages. What routing config do I need?" It will generate the correct file.

One advantage of building with Bolt.new is its AI assistant. You can ask it to generate deployment configuration in real time.

Open your Bolt project. In the AI chat sidebar, ask:

"I'm deploying to Netlify and subpages return 404. What routing configuration do I need?"

Bolt's AI will suggest the _redirects file syntax or vercel.json rules, depending on your target platform. It might even generate the exact file contents for you to copy-paste.

This works well for straightforward Netlify deployments. For complex setups (e.g., custom API routes, authentication redirects, multiple app contexts), the AI suggestion might need manual refinement. In those cases, use the AI output as a starting point and adjust it.

The reason this works: Bolt's AI has seen thousands of SPA deployments. It knows the pattern. If the AI-generated fix does not work, try the step-by-step manual instructions in this guide. Sometimes the AI flags edge cases it cannot fully resolve (if your Vercel project has existing rewrites, for example). Manual config gives you full control and confidence.

When should you escalate to Bolt support?

If your routing config is correct and 404s persist, or if your build logs show errors, contact Bolt support. Also escalate if you are unsure whether your Bolt project was built correctly for production deployment.

Most 404s are routing issues, and you can fix them yourself with the steps above. But some cases warrant support escalation.

Escalate to Bolt support if: your build logs show errors (e.g., "Prompt too large," "dependency not found"); you have added the correct routing config (Netlify _redirects or Vercel vercel.json) and redeployed, but subpages still return 404; your homepage is blank, not just subpages; or you are unsure if your Bolt project is set up for production deployment.

Before contacting support, prepare: a link to your deployed site, screenshots of your build logs, the routing config file you added, and a list of the exact subpages that fail. This speeds up diagnosis. Support can then check your deployment settings and Bolt project configuration directly.

Most Bolt support requests are resolved in hours. The team is responsive and knowledgeable about platform-specific quirks like this one.

How does managed hosting prevent this?

Managed platforms like Ship handle SPA routing automatically. No config files needed. Deploy your Bolt app and every route works out of the box. This eliminates routing config as a source of post-deployment errors.

If routing config feels like friction, managed hosting is the alternative. Platforms like Ship (which specializes in hosting Bolt and other AI-generated apps) detect that you are deploying an SPA and configure routing automatically. No _redirects files, no vercel.json, no 404.html workarounds.

This matters because static hosting platforms (Netlify, Vercel, GitHub Pages) are designed for flexibility: they host anything from static blogs to SPAs to serverless backends. That flexibility comes with a cost: you configure them. Managed platforms sacrifice flexibility for reliability. They are built for one thing: hosting modern web applications.

Here is the trade-off: Static hosting wins on price and on raw features (CDN customization, serverless functions, API routes). DIY self-hosted options win on raw cost per month (Hetzner plus Coolify is cheaper). Managed hosting wins on "just works" deployment and zero configuration.

If your team is small and deployment friction bothers you, managed hosting is worth the cost. You avoid 404 config mistakes, environment variable bugs, build timeouts, and other deployment gotchas. Your Bolt app deploys and works immediately. Ship is built exactly for this: you deploy with a git push, and the platform handles routing, environment variables, and app scaling.

This does not mean static hosting is wrong. Many teams love Netlify and do not mind routing config. But if you have hit this 404 issue, it is a data point: static hosting requires more configuration, especially for SPAs. Managed platforms eliminate that class of error entirely. For more details on how managed hosting works, see our guide on deploying AI apps to Ship.

Frequently Asked Questions

Why do subpages work in Bolt preview but not after deployment?

Bolt's dev server intercepts all requests and routes them to your SPA. Static hosts serve files from disk directly. Without routing config, subpages do not exist as files and return 404.

Does a 404 error mean my deployment failed?

No. A 404 usually means the deployment succeeded but the routing config is missing. Check your build logs first to confirm the build succeeded.

Do I need to fix the code or the config?

The config. Your Bolt app code is fine. The static host does not know how to route an SPA without a config file.

How long does it take for the _redirects file to work after deployment?

Usually 30 seconds to a minute. If you are still seeing 404s after 2 minutes, clear your browser cache and try again.

Can I test routing locally before deploying?

Yes. In Bolt's preview, routing always works. To test your routing config file before shipping to production, deploy to a staging environment first or ask Bolt's AI to review your config.

What if I am using a custom domain instead of a platform domain?

The routing config applies to your custom domain the same way. No difference in setup.

Is this a Bolt.new bug?

No. Every SPA framework (React, Vue, Next.js, Nuxt) requires routing config on static hosts. Bolt generates SPAs by default, so you encounter this every time you deploy.

The Bottom Line

404 errors on Bolt.new subpages after deployment are routing configuration errors, not code errors. The fix is a single file (_redirects for Netlify, vercel.json for Vercel, or 404.html for GitHub Pages) and a redeploy. This is expected friction with static hosting. If you want routing to "just work," managed hosting platforms like Ship eliminate this entire class of deployment error. Start with the routing config fix first; if you keep hitting similar issues, managed hosting might be worth the cost.