threejs-errors-rendering

threejs-errors-rendering

Debugging Workflow Checklist

When a Three.js scene does not render correctly, ALWAYS follow this sequence:

1. Open the browser console -- check for WebGL errors or Three.js warnings
2. Verify the renderer has a non-zero size (renderer.getSize(new THREE.Vector2()))
3. Confirm the canvas is in the DOM and visible (not display: none)
4. Check that renderer.render(scene, camera) is called (in a loop or at least once)
5. Verify the camera is looking at the scene (position, target, near/far)
6. Confirm at least one light exists for lit materials
7. Check material side, visible, opacity, and transparent properties
8. Verify object visible, layers, and frustumCulled properties
9. Inspect color space settings on renderer and textures

---

Symptom 1: Black Screen (Nothing Visible)

Cause A: Renderer has zero size

The canvas has 0x0 dimensions. This happens when setSize() is called before the container is in the DOM or when the container has no CSS dimensions.

Fix:

// ALWAYS ensure the container is in the DOM and has dimensions before setSize
document.body.appendChild(renderer.domElement);
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));

Cause B: Camera is inside the object or facing away

The camera is at (0, 0, 0) and the object is also at (0, 0, 0), so the camera is inside the mesh. Or the camera is pointing in the wrong direction.

Fix:

camera.position.set(0, 2, 5); // ALWAYS move camera away from origin
camera.lookAt(0, 0, 0);

Cause C: Near/far clipping planes exclude the object

Objects closer than near or farther than far are clipped. Default PerspectiveCamera near is 0.1, far is 2000.

Fix:

const camera = new THREE.PerspectiveCamera(75, aspect, 0.1, 1000);
// NEVER set near to 0 -- causes z-fighting and depth buffer issues
// ALWAYS keep far/near ratio below 100000 for stable depth precision