Mistakes 1-6: canvas and renderer assumptions
The first group happens before the model matters. The canvas has CSS size but no matching drawing buffer. The renderer never updates after resize. Pixel ratio is left uncapped on a phone. The scene renders once before assets arrive and never redraws. The render loop keeps running below the fold. The page assumes WebGL will always initialize.
Fix these by treating the canvas as part of the page system. Read the container size, call `renderer.setSize(width, height, false)`, update camera aspect, clamp device pixel ratio, and show useful HTML content even if the canvas fails. A WebGL scene should enhance the page, not hold it hostage.
Mistakes 7-12: model imports that look random
The second group shows up when GLB and GLTF files enter the scene. The model is loaded but offscreen. The object is too large or too tiny. The pivot sits far away from the visible mesh. The camera is guessed before bounds are known. Animation clips exist but are ignored. Object URLs from repeated uploads are never revoked.
The cure is an import checklist. Compute a Box3, log the size, move or wrap the model around a predictable center, fit the camera after load, list animation clips, and clean up temporary URLs. Imported assets are not just art files. They are runtime data that deserves inspection.
Mistakes 13-17: materials, color, and lighting
Many scenes break visually while the JavaScript is technically fine. MeshStandardMaterial is used without enough light. Metallic materials have nothing useful to reflect. Color textures and data textures share the wrong color-space assumptions. Tone mapping is copied from a demo without checking exposure. Shadows are enabled and then crush the object into a dark blob.
Use a neutral lighting preset before dramatic art direction. Set renderer output color space deliberately. Treat base-color maps differently from roughness, normal, and metalness maps. Add environment lighting when PBR materials need reflections. Keep shadows optional until the model is already readable.
Mistakes 18-22: interaction and UI drift
Interaction bugs make a scene feel cheap. OrbitControls damping is enabled but `controls.update()` is not called. Controls orbit around the origin instead of the model center. Raycaster coordinates are calculated from the window even though the canvas is inside a layout. Labels overlap the object or stay visible behind it. Click targets are too small for touch users.
These are not decoration issues; they are trust issues. Update controls in the right loop, set the target after fitting, compute pointer coordinates from canvas bounds, filter pickable objects, and design labels as a UI layer with visibility rules. If the user cannot control or understand the scene, the rendering quality does not matter.
Mistakes 23-27: publishing without a final pass
The final group appears when a demo becomes a public page. There is no loading state. Failed assets leave a blank rectangle. The scene has no source notes or related explanation. The article depends on canvas pixels that crawlers and reviewers cannot read. The page looks good on desktop but becomes unreadable or slow on mobile.
Before publishing, run the WebGL scene health check. Confirm loading, fallback copy, console cleanliness, mobile sizing, reduced-motion behavior, and internal links. Then ask whether the page still teaches something if the demo is unavailable. The best Three.js content is not just a working scene; it is a working explanation.
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 gotchas 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: Most Three.js failures are chains, not isolated lines of code. 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 27 Three.js mistakes that break WebGL scenes 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. A scene should be checked in asset, camera, render, interaction, and page layers. 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. Publishing quality depends on mobile behavior, loading states, and fallback content as much as the canvas. If any answer is fuzzy, fix that before introducing a new effect or a larger asset.
A compact pre-publish review
const review = {
canvas: ['resize buffer', 'clamp pixel ratio', 'fallback copy'],
assets: ['measure bounds', 'fit camera', 'check texture size'],
render: ['lighting readable', 'color space explicit', 'shadows bounded'],
interaction: ['controls target set', 'raycast from canvas bounds'],
publish: ['loading state', 'mobile QA', 'related guide links']
};
console.table(review);FAQ
When should I use 27 Three.js mistakes that break WebGL scenes?
Use it when your Three.js scene has a focused gotchas 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.