Do not debug everything at once
A blank canvas can come from a missing canvas size, an offscreen camera, a clipped object, a black material, a failed import, or a render loop that never runs. If you change all of those at once, you may hide the actual cause. Debug in layers and keep each test boring.
First prove the renderer can draw a basic cube with a MeshNormalMaterial. This material does not need lights, so it removes lighting from the question. If the cube appears, the renderer, camera, and loop are basically alive. If it does not, look at canvas sizing, WebGL context errors, and camera placement.
Check the camera next
A camera can look in the wrong direction, sit inside the object, or clip the object with near and far planes. Add a CameraHelper when using shadow cameras or complex rigs. For a PerspectiveCamera, start with a visible position, call `lookAt(0, 0, 0)`, and render a known object at the origin.
When loading unknown models, compute a bounding box and log its size. If the box is enormous or tiny, the camera may be fine and the scale may be the problem. If the box center is far from the origin, the object may be outside the camera's view.
Separate material and light issues
MeshStandardMaterial needs light. MeshBasicMaterial does not. MeshNormalMaterial provides an even stronger diagnostic because it colors surfaces by normal direction. Swap materials temporarily. If the object appears with a diagnostic material but disappears with its original material, inspect textures, color management, alpha settings, side settings, and lights.
For imported models, traverse the scene and count meshes. Log material names and visibility. It is possible for a loader to succeed while the visible content is hidden inside a nested hierarchy or assigned a fully transparent material.
Use helpers without shipping them
GridHelper, AxesHelper, BoxHelper, and light helpers are excellent during development. They reveal scale, orientation, and positions that are otherwise invisible. Add them through a debug flag so they can be toggled without editing the scene.
Before publishing, remove or hide debug helpers. A production page should feel intentional, but a development workflow should be full of instruments. The balance is simple: make problems visible while building, then keep only the helpful visual structure for users.
When this guide is the right tool
Use this guide when the problem is specific enough that a broad Three.js tutorial would waste time. The focus here is debugging in a real browser page: what to check first, what to measure, and what to avoid before the scene becomes harder to reason about.
The practical rule is simple: Prove the renderer works with a known cube before debugging imported assets. If that sentence describes the scene in front of you, treat the article as a checklist. Read the explanation, copy the smallest useful code pattern, then test the result in a narrow mobile viewport and a wide desktop viewport before adding more polish.
Common mistake to avoid
The common mistake is treating Three.js scene debugging checklist when nothing appears as a visual tweak instead of a scene-system decision. Three.js problems often look like one broken line of code, but the actual issue is usually a chain: asset assumptions, renderer settings, camera math, material setup, interaction state, and page layout all meet inside the canvas.
That is why the safest fix is incremental. Start from a known-good scene, change one variable, and keep a visible diagnostic while testing. Check camera position, near/far planes, object scale, and material visibility in order. When the scene works, remove temporary helpers and leave behind only the checks that make sense for users.
Publishing check
Before publishing, run the scene through three questions. Does the page remain useful if WebGL fails or the asset loads slowly? Does the same scene still read clearly on a phone? Can another developer understand the important settings without reverse-engineering the whole file?
The last pass should be boring on purpose: verify canvas size, console errors, mobile performance, source links, internal links, and the related guide path. Use helpers and console metrics temporarily, then remove them from production. If any answer is fuzzy, fix that before introducing a new effect or a larger asset.
Known-good diagnostic cube
scene.add(new THREE.GridHelper(10, 10));
scene.add(new THREE.AxesHelper(2));
const cube = new THREE.Mesh(
new THREE.BoxGeometry(1, 1, 1),
new THREE.MeshNormalMaterial()
);
scene.add(cube);
camera.position.set(3, 2, 4);
camera.lookAt(0, 0, 0);
renderer.render(scene, camera);FAQ
When should I use Three.js scene debugging checklist when nothing appears?
Use it when your Three.js scene has a focused debugging problem and you need a practical checklist before adding more visual polish.
Is the code snippet production-ready?
Treat the snippet as a clear starting point. Test it in your scene, adapt naming and paths, and verify behavior on mobile hardware before publishing.
What should I check after applying this guide?
Run the scene through mobile sizing, console errors, loading states, source links, and related guide paths so the page remains useful even when assets or WebGL fail.