The black screen: how one failed texture unmounted my whole app

The problem

Every now and then, opening my home page gave me a completely black screen. Not a slow page, not a broken layout: nothing at all. Refreshing usually fixed it, which made it even harder to track down.

The details

The first step was to rule things out.

Was it the server? I fetched the raw HTML the server sends, before any JavaScript runs. The hero text was there, so the server was rendering the page correctly.

Was it the page transition? My page transition covers the screen while JavaScript loads. But I checked what it looks like without JavaScript: a full orange screen, not black. So the black screen happened after JavaScript started.

That pointed at something crashing on the client. On the home page, the most fragile piece was a 3D hover effect built with React Three Fiber. It loads eight project images from imgur as textures:

const textures = useLoader(TextureLoader, projects.map((p) => p.src));

If any one of those eight requests fails, useLoader throws. And React Three Fiber re-throws errors from inside <Canvas> into the normal React tree. I confirmed it in the library source:

if (block) throw block;
if (error) throw error;

The app had no error boundary: no error.tsx, no global-error.tsx. So one failed texture unmounted the entire application.

Why black? Because the page background is #000, and Next.js's default error message has no colors of its own. Dark text on a black page looks exactly like "nothing loaded".

The challenges

• It was intermittent. All eight images loaded fine every time I tested. It only failed when imgur rate-limited or the network blipped.
• The symptom was misleading. A black screen suggests a CSS or loading problem, not a JavaScript exception.
• The error crossed library boundaries. The failure started inside the Three.js render tree and surfaced in React's tree, so the stack trace didn't point at my code.
• Other triggers looked the same. A WebGL context that fails to start, or a chunk that fails to load, ends in the exact same black screen.

The solution

I fixed it in three layers, from most specific to most general:

1. Remove the fragile dependency. The eight textures now live in my own public/textures/ folder instead of imgur.
2. Contain the blast radius. The 3D scene has its own error boundary. If it fails, only the effect disappears:

class SceneErrorBoundary extends React.Component {
  state = { hasError: false };
  static getDerivedStateFromError() { return { hasError: true }; }
  render() { return this.state.hasError ? null : this.props.children; }
}

1. Never show a blank page. I added app/error.tsx (a readable error inside the normal layout, with Reload and Try again buttons) and app/global-error.tsx, which uses inline styles so it still renders even if the CSS didn't load.

Lessons learned

• No error boundary means one bug takes down everything. Decorative features especially should fail quietly.
• Check what the user sees at each stage. Comparing the no-JavaScript state (orange) with the bug (black) narrowed the search fast.
• Read the library source when the docs are quiet. Two lines in React Three Fiber explained the whole bug.
• A dark theme hides default error pages. Always give your error states explicit colors.