How to Fix a Blank White Screen After Building a Lovable App

Why blank screens happen after building a Lovable app

A blank screen means your app's HTML loaded, but the JavaScript failed to execute and render your React components. The page is technically served — it is not a 404 — but nothing appears because the React app crashed silently before mounting. Lovable's own documentation identifies vite.config.ts issues as the primary cause. When the Lovable AI modifies your Vite configuration (for example, adding plugins, changing the base path, or introducing security headers), it can accidentally break how the build bundles your JavaScript. The built files either fail to load or load from the wrong path. Missing environment variables are the second most common cause. If your app tries to initialize a Supabase client with an undefined URL, or calls an API with a missing key, the initialization code throws an error before any component renders. This is especially common when deploying to production where Lovable Cloud secrets are not automatically available. The third category is runtime JavaScript errors — an undefined variable, a failed import, or a component that throws during render. React's default behavior is to unmount the entire component tree when an unhandled error occurs, leaving you with a blank white page and no visible indication of what went wrong.

• Misconfigured vite.config.ts — wrong base path, broken plugin, or injected security headers
• Missing VITE_ environment variables causing Supabase or API initialization to fail
• JavaScript runtime error crashing the React app before it mounts
• Asset path mismatch — built JS/CSS files referenced at paths that return 404
• Security headers (CSP, X-Frame-Options) accidentally blocking script execution
• Authentication logic redirecting to a blank or nonexistent route on load

Error messages you might see

Before you start

• A Lovable project that shows a blank screen after building or publishing
• Access to browser developer tools (right-click → Inspect → Console tab)
• Knowledge of whether the blank screen appeared after a specific change or on a fresh deploy

How to fix it

// Broken: AI added a wrong base path or CSP headers
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
export default defineConfig({
  base: '/my-app/',  // Wrong: causes all asset paths to break
  plugins: [react()],
  server: { headers: { 'Content-Security-Policy': "script-src 'none'" } },
});

// Fixed: standard Lovable Vite configuration
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import path from 'path';
export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
  server: {
    host: '::',
    port: 8080,
  },
});

// Crashes if VITE_SUPABASE_URL is undefined — causes blank screen
import { createClient } from '@supabase/supabase-js';
const supabase = createClient(
  import.meta.env.VITE_SUPABASE_URL,
  import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
);

// Safe initialization with fallback and error boundary
import { createClient } from '@supabase/supabase-js';
const url = import.meta.env.VITE_SUPABASE_URL;
const key = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY;
if (!url || !key) {
  console.error('Supabase environment variables are missing. Check Cloud tab → Secrets.');
}
export const supabase = createClient(url ?? '', key ?? '');

// No error boundary — any render error causes blank screen
import { BrowserRouter } from 'react-router-dom';
function App() {
  return (
    <BrowserRouter>
      <Routes>...</Routes>
    </BrowserRouter>
  );
}

// ErrorBoundary catches render errors and shows fallback UI
import { Component, type ReactNode } from 'react';
class ErrorBoundary extends Component<
  { children: ReactNode },
  { hasError: boolean; error: Error | null }
> {
  state = { hasError: false, error: null as Error | null };
  static getDerivedStateFromError(error: Error) {
    return { hasError: true, error };
  }
  render() {
    if (this.state.hasError) {
      return (
        <div style={{ padding: '2rem', fontFamily: 'sans-serif' }}>
          <h1>Something went wrong</h1>
          <pre style={{ color: 'red' }}>{this.state.error?.message}</pre>
          <button onClick={() => window.location.reload()}>Reload</button>
        </div>
      );
    }
    return this.props.children;
  }
}

Complete code example

1import { Component, type ReactNode } from 'react';
2
3interface ErrorBoundaryProps {
4  children: ReactNode;
5}
6
7interface ErrorBoundaryState {
8  hasError: boolean;
9  error: Error | null;
10}
11
12// Catches unhandled React rendering errors
13// and shows a fallback instead of a blank screen
14export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
15  constructor(props: ErrorBoundaryProps) {
16    super(props);
17    this.state = { hasError: false, error: null };
18  }
19
20  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
21    return { hasError: true, error };
22  }
23
24  componentDidCatch(error: Error, info: React.ErrorInfo) {
25    // Log the error for debugging
26    console.error('ErrorBoundary caught:', error, info.componentStack);
27  }
28
29  render() {
30    if (this.state.hasError) {
31      return (
32        <div className="flex flex-col items-center justify-center min-h-screen p-8">
33          <h1 className="text-2xl font-bold mb-4">Something went wrong</h1>
34          <p className="text-gray-600 mb-4">
35            The app encountered an error. Check the browser console for details.
36          </p>
37          <pre className="bg-red-50 text-red-700 p-4 rounded mb-4 max-w-lg overflow-auto">
38            {this.state.error?.message}
39          </pre>
40          <button
41            onClick={() => window.location.reload()}
42            className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700"
43          >
44            Reload Page
45          </button>
46        </div>
47      );
48    }
49    return this.props.children;
50  }
51}

Best practices to prevent this

• Always check the browser console first — the blank screen hides the real error but the console reveals it
• Keep vite.config.ts simple and close to the default Lovable configuration — avoid adding custom base paths or security header middleware
• Add an ErrorBoundary component wrapping your Router so rendering failures show a message instead of a blank page
• Validate environment variables at startup with console.warn so missing config is immediately visible
• Test your production build after every major change — issues often only appear in the built version, not in preview
• Use the Try-to-fix button when it appears on preview errors — it costs no credits and often resolves the issue automatically
• Keep version history in mind — before making large changes, note the current version so you can revert quickly if the screen goes blank

Still stuck?

Copy one of these prompts to get a personalized, step-by-step explanation.

Related error patterns