Debugging 3D Sites

3D websites fail differently from regular websites. A broken CSS layout looks wrong. A broken Three.js scene often shows nothing at all, a black canvas, a white screen, or an invisible error.

This lesson gives you the debugging system that fixes 3D sites fast.

The three-step debug process

Always do these three things before sending anything to Claude.

Step 1: Open the console

Press F12 in Chrome or Edge. Click the Console tab. Look at the output.

A working 3D site shows no red errors. A broken 3D site almost always shows a red error with a line number. Copy the entire error message including the file name and line number before doing anything else. That error is the answer.

Step 2: Identify which file the error is in

Three.js errors from main.js usually say something is not defined, cannot read properties of undefined, or is not a constructor. These are structural errors where Claude used the wrong Three.js syntax or referenced something before it was created.

CDN load errors from index.html say "Failed to load resource" or show a 404. These mean the script tag URL is wrong or the file loaded in the wrong order.

GSAP errors say "ScrollTrigger is not defined" or "gsap is not defined." These mean the CDN loaded in the wrong order.

Step 3: Send the error to Claude with context

My 3D website is showing this error in the browser console:

[PASTE THE COMPLETE ERROR MESSAGE AND LINE NUMBER]

This error appeared when I: [opened the page / scrolled / moved the mouse]

The 3D effect is: [describe what you see — nothing, black canvas, visible but not moving]

Fix only the code that caused this error. Do not change anything else.

The most common 3D site problems

Nothing appears on screen

The canvas is there but the 3D scene is invisible. Common causes and their fixes.

Camera looking the wrong way: the geometry was created at origin 0,0,0 but the camera was also placed at 0,0,0 so they are in the same spot. The camera should always be positioned on the Z axis looking toward the origin.

The 3D canvas renders but the scene is completely invisible.

Check that the camera is positioned at z: 5 looking at the origin with 0,0,0.

Confirm the geometry exists at position 0,0,0 and is not placed behind the camera.

Black canvas instead of transparent background: if the canvas should be transparent but shows black, both of these are required together and neither works without the other.

The canvas is showing as a solid black background.

Two changes are required together:

1. In the renderer constructor add alpha: true
2. Call renderer.setClearColor(0x000000, 0) after creating the renderer

Both must be present. Fix this in main.js.

Scene appears but immediately goes black after a moment: the animation loop is not running. The renderer.render call needs to be inside a requestAnimationFrame loop.

The 3D scene flashes visible for one frame then goes black.

The render call is probably not inside the animation loop.

Ensure the animate function calls requestAnimationFrame(animate) and

renderer.render(scene, camera) every frame.

Three.js syntax errors

Three.js changes between versions and the Claude training data contains multiple versions. If your CDN loads r128 but Claude wrote r134 syntax, you will see constructor errors.

Three.js is throwing this constructor error: [PASTE ERROR]

I am using Three.js r128 from this CDN:

• https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js
• Rewrite any incompatible Three.js syntax to work correctly with r128.

In r128 use Geometry and not BufferGeometry for simple shapes unless

BufferGeometry is specifically needed for particles.

GSAP ScrollTrigger not working

If GSAP animations run once but are not scrubbed to scroll:

• The GSAP animation plays on page load but is not connected to scroll position.
• I want the animation scrubbed to scroll using ScrollTrigger.

Ensure:

1. The ScrollTrigger CDN loads after the GSAP CDN in index.html head
2. gsap.registerPlugin(ScrollTrigger) is called at the top of main.js
3. The ScrollTrigger object uses scrub: 1 and trigger pointing to the correct section

Mouse interaction not responding

If moving the mouse has no visible effect on the 3D scene:

The mouse interaction is not working. Moving the cursor has no effect on the 3D scene.

Debug the mouse event listener:

1. Add a console.log(e.clientX, e.clientY) inside the mousemove handler to confirm

the event is firing

1. Confirm the mouse coordinates are being converted from pixel space to normalised

device coordinates between -1 and 1

1. Confirm the converted coordinates are being applied to the Three.js object each frame

Fix whatever is broken in main.js.

Performance problems

If the 3D site runs at low frame rate or the page feels laggy:

The 3D site is running slowly and not at 60 frames per second.

Apply these performance fixes:

1. Set renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)) to limit

high-DPI rendering on retina screens

1. If using particles, reduce to 500 on mobile screens under 768px
2. Add willReadFrequently: true to the canvas context if reading pixel data
3. Move any geometry or material creation outside the animation loop so it

only runs once on initialisation and not 60 times per second

Canvas sizing and resize issues

If the 3D canvas does not fill its container or breaks on window resize:

The Three.js canvas is not resizing correctly when the browser window is resized.

Add a window resize handler that:

1. Updates renderer.setSize(container.clientWidth, container.clientHeight)
2. Updates camera.aspect to the new aspect ratio
3. Calls camera.updateProjectionMatrix() after changing the aspect ratio

If the canvas fills the full screen the container is window.innerWidth and

window.innerHeight.

If the canvas fills a specific div, measure that div's dimensions using

getBoundingClientRect() and update accordingly.

When the fix makes something else break

Sometimes fixing one thing in a 3D file breaks something that was working. This happens because Three.js files are interdependent, where the renderer setup, the animation loop, the geometry, the lights, and the event listeners all reference each other.

When this happens:

The previous fix resolved [ISSUE A] but now [ISSUE B] is broken.
Here is the current console error: [PASTE ERROR]
Here is what ISSUE B looks like: [DESCRIBE WHAT YOU SEE]

Fix ISSUE B without reverting the ISSUE A fix.

The pattern is always the same: describe what is broken now, describe what you see, paste the console error. Claude has the full context of the file it built and can apply targeted fixes without needing to rebuild everything.

Your action right now

Open your 3D site in Chrome and press F12. Check the Console tab. If there are any yellow warnings or red errors, copy them and fix them now before moving to the deployment lesson.

A site with zero console errors and a visible 3D effect is ready to deploy.