Sign in Get started
← Blog

Bolt.new Site Deploys but Shows a Blank Page: What Broke

By Yoni Ryabinski

When your bolt.new deployed site blank screen appears right after a successful deployment, your hosting platform did not drop the ball—your application crashed during its first client-side render. Your host (such as Netlify) returned a valid HTTP 200 OK status code and served your index.html file, but an unhandled JavaScript exception broke execution in the browser before any visual elements could mount to the DOM.

For non-technical founders and vibe-coders building live products with Bolt, this failure mode is uniquely frustrating. Your deployment dashboard displays a reassuring green checkmark, your build logs conclude with "Site deploy was successful," yet your customers see nothing but a pure white page. Understanding why this happens and following a structured diagnostic sequence will help you pinpoint the broken line of code, patch the configuration, and prevent silent outages from reaching your users.

The Green Checkmark Illusion: Build Success vs. Runtime Crash

To fix a blank screen, you must first separate the build phase from the runtime phase. When Bolt.new bundles an application using tools like Vite, it compiles your React, Vue, or Svelte components into static HTML, JavaScript, and CSS files. During this build phase, Vite checks whether your syntax is valid JavaScript and ensures that all static imports resolve to actual files on disk.

If your syntax is valid, the build succeeds. The hosting provider takes those bundled files, places them on a Content Delivery Network (CDN), and serves them to anyone visiting your domain. However, the build system does not execute your application logic the way an actual user's browser does. It does not initiate network calls to your third-party APIs, it does not evaluate client-side state transitions, and it does not check whether secret API tokens or environment variables exist in production.

The moment a real visitor navigates to your live URL, their browser downloads the JavaScript bundle and begins executing code top-to-bottom. If that bundle tries to read an undefined property—such as an API configuration object that only existed inside Bolt's WebContainer environment—the browser throws an uncaught runtime exception. React or your underlying framework immediately halts the rendering pipeline to prevent unpredictable behavior, leaving the root element (<div id="root"></div>) completely empty.

If you have recently updated your project and suspect an old version is being served instead of your changes, you can explore how caching affects releases in our walkthrough on stale builds served after deploy.

The 4 Most Common Causes of a Blank Bolt.new Deployment

In over many cases where a Bolt.new application builds cleanly but renders a white screen on Netlify or custom hosting, the culprit traces back to one of four configuration oversights.

1. Missing Environment Variables on the Production Host

Inside Bolt.new, your project runs in a pre-configured browser development environment. Bolt often populates environment variables automatically behind the scenes (or injects them directly into local memory). When you click the "Deploy" button to export your codebase to Netlify or download the repository, those private variables do not automatically copy over to your production hosting provider's dashboard.

Furthermore, front-end build tools enforce strict naming conventions for variables exposed to the client. According to the Vite documentation on environment variables, only variables prefixed with VITE_ are embedded into the client-side JavaScript bundle during the build. If your code references a variable named SUPABASE_URL instead of VITE_SUPABASE_URL, Vite compiles that reference to undefined.

Consider this standard initialization block in a Bolt-generated app:

import { createClient } from '@supabase/supabase-js';

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL;
const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY;

// If these variables are not set on your host, supabaseUrl is undefined
export const supabase = createClient(supabaseUrl, supabaseAnonKey);

When the Supabase client library receives an undefined URL during startup, its constructor throws a fatal error: supabaseUrl is required. Because this happens at module initialization time—before your root component mounts—the entire page execution collapses instantly.

2. API URLs Still Pointing to Localhost

Bolt.new frequently writes helper functions or mock backends that default to local addresses during the prototyping phase. You might find lines like this scattered across your data-fetching services:

const API_BASE = import.meta.env.VITE_API_URL || 'http://localhost:3000/api';

export async function loadUserData() {
  const res = await fetch(`${API_BASE}/user`);
  return res.json();
}

While working inside Bolt's preview pane, a local mock server might answer those requests. But when deployed to a live domain on the internet, your user's browser attempts to query http://localhost:3000/api on their own physical computer. The request fails instantly with a net::ERR_CONNECTION_REFUSED error. If your root component does not wrap this initial fetch in a try/catch block or loading boundary, the unhandled rejection crashes the page.

3. Missing Base Path or Broken Asset Routing

If your production site is hosted on a subpath (for example, mybrand.com/app/) or if your host does not correctly map single-page application (SPA) routes back to index.html, the browser will fail to fetch your bundled JavaScript files entirely.

In your vite.config.ts file, the base configuration dictates how asset URLs are written into your HTML. If base is set to an absolute root path like /, but your hosting configuration expects relative asset paths, the browser will request https://yourdomain.com/assets/index-D1a2B3c.js instead of the correct location, receiving a 404 response. Without its JavaScript files, the page remains static blank HTML.

4. Dev-Only Routes or Unhandled Mock Providers

Bolt often provisions mock authentication providers or development-only test routes so you can click around your app without setting up real user accounts. If your router (such as React Router) attempts to load a mock context provider that was stripped out of the production bundle, the routing tree fails to resolve a valid element to mount.

To understand the full spectrum of issues that can disable an AI-generated project, check out our comprehensive guide on troubleshooting broken Bolt applications, where we cover routing mismatches, broken state models, and third-party script conflicts.

How to Diagnose the Blank Page in Under 60 Seconds

You do not need an engineering degree to identify why your live deployment is white. Your web browser includes an exact log of every script failure that occurs on the page.

Step 1: Open the Browser Developer Console

Navigate to your live, blank production URL in Google Chrome, Brave, or Mozilla Firefox. Open Developer Tools using the keyboard shortcut:

  • macOS: Press Cmd + Option + J
  • Windows / Linux: Press Ctrl + Shift + J (or F12)

Select the Console tab. If your app crashed due to a runtime error, you will see bright red text detailing the failure. As explained in the MDN Web Docs on console error reporting, the console outputs the exact error message along with a stack trace showing which file and line triggered the exception.

Common red error messages include:

  • Uncaught TypeError: Cannot read properties of undefined (reading 'split') — A component tried to format a piece of data (like a user email or API key) that was rarely provided.
  • Uncaught Error: supabaseUrl is required — You forgot to supply your Supabase database URL in your host's environment settings.
  • Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "text/html" — Your asset URLs are pointing to the wrong path, and your host is returning an error page instead of the real script.

Step 2: Check the Network Tab for 404s

Click over to the Network tab inside DevTools, ensure the "All" filter is active, and press Cmd + R (or Ctrl + R) to reload the page. Look down the list of requests:

  • Check your .js and .css files. If any of them display a red 404 Not Found status code, your asset paths or build directory settings are misconfigured.
  • Check your API calls. If your app attempts to contact an external endpoint during load and receives a 401 Unauthorized or 403 Forbidden, your production API keys are either missing or expired.

Step 3: Review Host Deployment Logs

Log in to your hosting provider (such as Netlify). Head to your site overview and review the current deploy log. Look for build warnings that developers often dismiss, such as:

[vite] "VITE_API_URL" is not defined in .env or environment variables.
(!) "supabaseAnonKey" is dynamically imported but undefined.

According to the official Netlify documentation on environment variables, any variable required during the build or client execution must be explicitly configured in the site dashboard under Site configuration > Environment variables. If a variable is missing during the build, Vite replaces it with an empty value without stopping the build, deferring the disaster to your live visitors.

The Correct Fix Sequence

Do not guess and randomly edit prompts inside Bolt. Follow this structured three-step remediation workflow to get your live app back online cleanly.

  1. Configure Environment Variables on Your Production Host:

    Open your Bolt project and inspect your .env or .env.example file to identify every key your application uses. Then open your hosting dashboard (Netlify, Vercel, or Cloudflare Pages), navigate to project settings, and paste those exact key-value pairs into the production environment section. Ensure that all keys required by the browser begin with VITE_.

  2. Trigger a Clean Redeploy Without Cache: Simply saving variables in your host dashboard does not update an already-built site. Static sites must be re-compiled so Vite can embed the new values into the generated JavaScript bundles. In Netlify, click Deploys > Trigger deploy > Clear cache and deploy site . This forces the server to start with fresh dependencies and read your configured variables.
  3. Perform a Hard Refresh in Your Browser:

    Modern web browsers aggressively cache JavaScript assets. If you visit your URL immediately after a redeploy, your browser may continue executing the old, broken script bundle stored in local disk cache. Perform a hard refresh using Cmd + Shift + R (Mac) or Ctrl + F5 (Windows) to verify that the app now mounts cleanly.

If you run into persistent initialization crashes or broken builds across multiple platforms, our team can help walk you through resolving them directly via our dedicated Bolt fix and recovery service.

Why Traditional Uptime Monitors Miss Blank Pages

Most founders assume that setting up a free ping monitor or basic uptime tool will notify them if their application breaks. Unfortunately, standard uptime monitors operate at the HTTP networking level: they ping your server, receive an HTTP 200 OK response, and assume everything is working perfectly.

A blank page caused by a client-side JavaScript crash still returns an HTTP 200 status code . The CDN successfully delivered the HTML container file, so your ping check reports a healthy green status while every real customer who visits your page sees a lifeless white screen. Without automated checks that evaluate the actual content rendered on your live site, you will only discover outages when an angry customer sends an email or cancels their subscription.

Effective monitoring for modern, client-rendered web applications requires synthetic checks that inspect the page beyond the initial network response, ensuring that critical text, navigation elements, or application wrappers actually render on screen.

How Nightlamp App Care Protects Your Live Application

When you are a non-technical founder running a live business, you should not have to spend your weekends decrypting browser console stack traces or wondering whether your current prompt broke your production bundle. You need an operational safety net that watches your site continuously and explains problems in plain English.

Nightlamp is managed monitoring and diagnostics for your app's availability and delivery. Rather than inundating you with complex telemetry charts or cryptic error codes, Nightlamp provides App Care: when something breaks, human engineers diagnose incidents for you; Nightlamp does not just fire alerts.

Here is how Nightlamp keeps your Bolt application running smoothly:

  • Synthetic and Uptime Checks: Nightlamp monitors HTTP/uptime for any public URL and verifies that your application actually displays real content, catching silent blank-page failures before your customers do.
  • Critical Flow Verification: Nightlamp runs synthetic checks, including magic-link and email-delivery flow monitoring via AgentDraft, guaranteeing that your authentication and transactional messaging systems function continuously.
  • Core Infrastructure Hygiene: Nightlamp monitors SSL/TLS certificate expiry, tracks DNS records and DNSBL blocklists, watches SMTP/mail servers, and monitors scheduled cron heartbeat jobs.
  • Human-Led Diagnosis: Nightlamp does not auto-remediate infrastructure on its own; a real engineer diagnoses each incident and tells you exactly what to fix. Response is led directly by founding engineer Yoni Ryabinski, giving you actionable, step-by-step guidance to resolve errors fast.

Frequently Asked Questions

Why does my Bolt app work perfectly in the preview pane but turn blank when published?

Bolt's preview pane runs inside an integrated WebContainer environment where local mock servers, automatic environment polyfills, and development configurations are active. When you publish to an external host, your code is compiled for production. If your production environment is missing critical environment variables or relies on mock APIs that only exist in development, the client-side JavaScript bundle crashes upon loading.

How do I know if my blank page is caused by an environment variable?

Open your browser's Developer Tools ( Cmd + Option + J on Mac or Ctrl + Shift + J on Windows) and look at the Console tab. If you see errors containing undefined , API key missing , or createClient failures, your application attempted to initialize a service using an environment variable that was rarely set on your host.

Do I need to rebuild my app after adding environment variables in Netlify?

Yes. Vite embeds client-accessible environment variables (those prefixed with VITE_) directly into static JavaScript files during compilation. Changing variables in your hosting settings does not alter previously compiled files. You must trigger a new deploy with cache cleared to incorporate the new values.

Can a basic uptime monitor alert me when my site displays a blank page?

No. Standard uptime monitors only verify that your web server answers with an HTTP 200 status code. Because a blank single-page app successfully serves its index.html file, an HTTP ping tool considers the site healthy. You need synthetic monitoring that checks for the presence of actual page elements to detect client-side runtime crashes.

Do not wait for paying customers to report that your app has vanished behind a white screen. Nightlamp is a paid managed service with a 14-day free trial; plans start at $79/mo for Watchtower, with human engineers diagnosing your incidents so you always know what broke and how to fix it. Explore our plans and start your trial today at Nightlamp Pricing.