I’ve run into similar head-scratching issues with @react-three/fiber before, so let’s break down why this might be happening even when WebGL works elsewhere, and how to fix it step by step.

Common Causes & Fixes #

1. React Strict Mode Triggering Duplicate WebGL Contexts (Development Only) #

React 18’s Strict Mode doubles-renders components in development to catch side effects. Since every <Canvas> creates a unique WebGL context, this can hit the browser’s limit on concurrent WebGL contexts (usually 8, but sometimes lower depending on your GPU/browser). This is a super common gotcha in Vite/Create React App setups, which enable Strict Mode by default.

Fix:

• Temporarily disable Strict Mode in your entry file (like main.jsx) by removing the <StrictMode> wrapper around your app. If the error vanishes, you’ve found the culprit.
• For production, Strict Mode doesn’t double-render, so this won’t be an issue. In development, you can either keep it disabled or optimize context creation to avoid duplicates.

2. Container Element Missing Valid Dimensions on Initial Render #

WebGL contexts require the canvas to have non-zero width/height values. If your <Canvas> parent div uses relative units (like vh) that the browser hasn’t fully calculated on first render, the canvas might try to initialize with 0x0 dimensions—leading to context creation failure.

Fix:

• Add explicit dimensions directly to the <Canvas> component, not just its parent:

  <Canvas style={{ width: '100%', height: '100%' }} ... />
  

• Replace useEffect with useLayoutEffect for mobile detection to set the isMobile state before the Canvas mounts:

  const [isMobile, setIsMobile] = useState(false);
  useLayoutEffect(() => {
    const mediaQuery = window.matchMedia("(max-width: 500px)");
    setIsMobile(mediaQuery.matches);
    const handleChange = (e) => setIsMobile(e.matches);
    mediaQuery.addEventListener("change", handleChange);
    return () => mediaQuery.removeEventListener("change", handleChange);
  }, []);
  

3. Conflicting WebGL Context Attributes #

The gl prop you set (preserveDrawingBuffer: true) might be asking for a context feature your browser can’t support, or conflicting with default attributes. Even if you removed it temporarily, residual state or other custom attributes could cause issues.

Fix:

• Start with a minimal Canvas configuration, removing all custom gl attributes and extra props:

  <Canvas camera={{ position: [20, 3, 5], fov: 25 }}>
  

• Reintroduce props one by one to identify which attribute is causing the conflict. preserveDrawingBuffer is rarely needed and often causes performance/context issues, so avoid it unless absolutely necessary.

4. Race Condition with Mobile Detection State #

Your isMobile state initializes to false and updates after the first render. Rapid re-renders right after initial context creation can sometimes destabilize the WebGL context, especially with complex scenes.

Fix:

• Initialize isMobile synchronously on mount instead of waiting for useEffect:

  const [isMobile, setIsMobile] = useState(() => 
    window.matchMedia("(max-width: 500px)").matches
  );
  

  This way, the correct isMobile value is available before the Canvas renders its content.

5. Browser Extensions or GPU Throttling #

Even if get.webgl.org works, extensions like ad blockers, privacy tools, or VPNs might interfere with WebGL context creation in more complex React apps. GPU power-saving modes (common on laptops) can also throttle WebGL when multiple tabs are open or resources are low.

Fix:

• Test your app in incognito mode to disable all extensions.
• Switch your GPU to high-performance mode (on Windows: go to Graphics Settings > Choose an app to set preference > select your browser > set to High Performance).
• Close other resource-heavy tabs/apps to free up GPU memory.

6. Exceeding Browser WebGL Context Limits #

Browsers cap the number of concurrent WebGL contexts per page. If your app accidentally creates multiple contexts (e.g., due to Strict Mode, or hidden Canvas components), you might hit this limit.

Fix:

• Ensure only one <Canvas> is rendered at a time.
• Check for third-party libraries that might be creating WebGL contexts in the background.

Step-by-Step Debugging Guide #

1. Disable Strict Mode First: This is the fastest check for development environments. If the error goes away, you’re done (for dev at least).
2. Simplify the Canvas: Strip it down to a basic cube to rule out asset/control conflicts:

   <Canvas>
     <mesh>
       <boxGeometry />
       <meshBasicMaterial color="red" />
     </mesh>
   </Canvas>
   

   If this works, add back your model, controls, and lights one by one to find the culprit.
3. Inspect Canvas Dimensions: Use browser dev tools to check the Canvas element’s width/height on initial render. Ensure it’s non-zero.
4. Check for Hidden Warnings: Look for subtle warnings in the console before the WebGL error—these often point to root causes (like silent asset loading issues).

Final Notes #

In your specific case, React Strict Mode or container dimension timing issues are the most likely culprits. Start with those two fixes, then work through the other steps if needed. Once you narrow down the cause, you can adjust your setup to keep both functionality and best practices intact.