threejs-errors-rendering
Use when a Three.js scene renders incorrectly: black screen, invisible objects, wrong colors, z-fighting, or broken shadows. Prevents the common mistake of wrong color space, missing material.side, or forgetting updateProjectionMatrix. Covers all common rendering errors with diagnosis steps and fix patterns. Keywords: black screen, invisible, wrong color, z-fighting, shadow artifact, rendering error, debug, nothing visible, dark, broken, nothing shows, model not appearing, screen is blank.
- License 许可
- MIT
- 最近更新
- 2026-11-06
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- threejs-errors-rendering
- license
- MIT
- metadata
- { "author": "OpenAEC-Foundation", "version": "1.0" }
- description
- Use when a Three.js scene renders incorrectly: black screen, invisible objects, wrong colors, z-fighting, or broken shadows. Prevents the common mistake of wrong color space, missing material.side, or forgetting updateProjectionMatrix. Covers all common rendering errors with diagnosis steps and fix patterns. Keywords: black screen, invisible, wrong color, z-fighting, shadow artifact, rendering error, debug, nothing visible, dark, broken, nothing shows, model not appearing, screen is blank.
- compatibility
- Designed for Claude Code. Requires Three.js r160+.
02 资源文件 4
- 其他.gitkeep—
- 参考文档references/anti-patterns.md7.4 KB
- 参考文档references/examples.md7.5 KB
- 参考文档references/methods.md4.8 KB
03 SKILL.md 正文
threejs-errors-rendering
Debugging Workflow Checklist
When a Three.js scene does not render correctly, ALWAYS follow this sequence:
- Open the browser console -- check for WebGL errors or Three.js warnings
- Verify the renderer has a non-zero size (
renderer.getSize(new THREE.Vector2())) - Confirm the canvas is in the DOM and visible (not
display: none) - Check that
renderer.render(scene, camera)is called (in a loop or at least once) - Verify the camera is looking at the scene (position, target, near/far)
- Confirm at least one light exists for lit materials
- Check material
side,visible,opacity, andtransparentproperties - Verify object
visible,layers, andfrustumCulledproperties - 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
Cause D: No light in the scene
MeshStandardMaterial, MeshPhongMaterial, and MeshLambertMaterial require lights. Without light, they render black. MeshBasicMaterial does NOT require lights.
Fix:
scene.add(new THREE.AmbientLight(0xffffff, 0.5));
scene.add(new THREE.DirectionalLight(0xffffff, 1));
Cause E: render() is never called
The animation loop is not started, or renderer.render(scene, camera) is missing.
Fix:
function animate() {
requestAnimationFrame(animate);
renderer.render(scene, camera);
}
animate(); // ALWAYS call the function to start the loop
Cause F: Scene or camera is wrong reference
Passing an empty scene or an uninitialized camera to render().
Diagnosis: Log scene.children.length and camera.type before the render call.
Symptom 2: Invisible Objects
Cause A: Wrong material side
Back faces are culled by default (FrontSide). If the camera sees the back of a plane or thin geometry, it is invisible.
Fix:
const material = new THREE.MeshStandardMaterial({
side: THREE.DoubleSide // ALWAYS use for planes, leaves, thin objects
});
Cause B: opacity without transparent
Setting opacity: 0.5 without transparent: true has NO effect.
Fix:
const material = new THREE.MeshStandardMaterial({
opacity: 0.5,
transparent: true // ALWAYS pair with opacity < 1
});
Cause C: Object on a different layer
The camera and the object MUST share at least one layer. By default both are on layer 0. If the object is moved to another layer, the camera must enable that layer too.
Fix:
object.layers.set(1);
camera.layers.enable(1); // camera must see layer 1
Cause D: visible is false (inherited)
visible = false on a parent makes ALL descendants invisible. Check the full parent chain.
Diagnosis:
let node = object;
while (node) {
if (!node.visible) console.log('Hidden ancestor:', node.name || node.type);
node = node.parent;
}
Cause E: frustumCulled incorrectly
If the bounding sphere is wrong (e.g., after manual vertex changes without computeBoundingSphere()), the object may be culled even when visible.
Fix:
geometry.computeBoundingSphere(); // ALWAYS call after modifying positions
// Or disable frustum culling for objects that must always render:
mesh.frustumCulled = false;
Cause F: Object at wrong position or scale 0
Object is at a position far from the camera, or scale.set(0, 0, 0).
Diagnosis: Log object.position, object.scale, object.matrixWorld.
Symptom 3: Wrong Colors
Cause A: Color space mismatch
This is the MOST COMMON color error in Three.js r160+.
Rules:
- Color/diffuse/emissive textures: ALWAYS set
texture.colorSpace = THREE.SRGBColorSpace - Data textures (normal, roughness, metalness, AO, displacement): ALWAYS leave as
THREE.LinearSRGBColorSpace - Renderer output:
renderer.outputColorSpace = THREE.SRGBColorSpace(default in r160+)
Symptoms of wrong color space:
- Washed-out colors: data texture incorrectly set to
SRGBColorSpace(double gamma) - Over-saturated colors: color texture left in
LinearSRGBColorSpace(no gamma applied)
Fix:
const texture = await loader.loadAsync('diffuse.png');
texture.colorSpace = THREE.SRGBColorSpace; // for color textures
const normalMap = await loader.loadAsync('normal.png');
// NEVER set SRGBColorSpace on normal maps -- corrupts surface data
Cause B: Tone mapping not configured
Without tone mapping, HDR values are clamped, producing flat or incorrect colors.
Fix:
renderer.toneMapping = THREE.ACESFilmicToneMapping; // or AgXToneMapping
renderer.toneMappingExposure = 1.0;
Cause C: Material color set after construction ignored
material.color.set() works, but material.color = new THREE.Color() after construction also works. The common mistake is setting color as a hex number directly: material.color = 0xff0000 does NOT work.
Fix:
material.color.set(0xff0000); // Correct
material.color = new THREE.Color(0xff0000); // Correct
// material.color = 0xff0000; // WRONG -- silently fails
Symptom 4: Z-Fighting (Flickering Surfaces)
Z-fighting occurs when two surfaces overlap at nearly the same depth, causing the depth buffer to alternate between them.
Fix A: Polygon offset
const material = new THREE.MeshStandardMaterial({
polygonOffset: true,
polygonOffsetFactor: -1,
polygonOffsetUnits: -1
});
Fix B: Logarithmic depth buffer
const renderer = new THREE.WebGLRenderer({ logarithmicDepthBuffer: true });
// Trades performance for better depth precision across large near/far ranges
// NEVER use with EffectComposer post-processing -- causes artifacts
Fix C: Position offset
Move one surface slightly:
decalMesh.position.z += 0.01; // small offset to prevent overlap
Fix D: Reduce near/far ratio
// ALWAYS keep the near plane as large as possible
camera.near = 1; // not 0.001
camera.far = 1000; // not 1000000
camera.updateProjectionMatrix();
Symptom 5: Shadow Artifacts
For complete shadow configuration, see the threejs-impl-shadows skill. Common quick fixes:
- No shadows at all:
renderer.shadowMap.enabled = true,light.castShadow = true,mesh.castShadow = true,ground.receiveShadow = true - Shadow acne (stripes): Increase
light.shadow.bias(e.g.,-0.005) - Peter panning (shadow detached):
light.shadow.biasis too large, reduce it - Low-res shadows: Increase
light.shadow.mapSize.set(2048, 2048)
Symptom 6: WebGL Context Lost
The browser reclaims the WebGL context under memory pressure or GPU reset.
Recovery pattern
renderer.domElement.addEventListener('webglcontextlost', (event) => {
event.preventDefault(); // ALWAYS prevent default to allow restoration
cancelAnimationFrame(animationId);
}, false);
renderer.domElement.addEventListener('webglcontextrestored', () => {
// Re-initialize materials, textures, render targets
initScene();
animate();
}, false);
NEVER ignore context loss -- the canvas goes black permanently. ALWAYS add both event listeners.
Symptom 7: needsUpdate Missing
BufferAttribute
After modifying vertex data, the GPU buffer is stale:
positions.array[0] = newX;
positions.needsUpdate = true; // ALWAYS set after modifying attribute data
Material
After changing structural properties (adding/removing maps, changing defines):
material.map = newTexture;
material.needsUpdate = true; // triggers shader recompilation
// NEVER set needsUpdate = true every frame -- causes constant recompilation
Texture
After modifying texture image data:
texture.image = newImage;
texture.needsUpdate = true; // triggers GPU re-upload
InstancedMesh
After setMatrixAt() or setColorAt():
mesh.instanceMatrix.needsUpdate = true; // ALWAYS after setMatrixAt
mesh.instanceColor.needsUpdate = true; // ALWAYS after setColorAt
Symptom 8: updateProjectionMatrix Required
ALWAYS call camera.updateProjectionMatrix() after changing:
camera.fovcamera.aspectcamera.nearcamera.farcamera.zoomcamera.left/right/top/bottom(OrthographicCamera)
window.addEventListener('resize', () => {
camera.aspect = window.innerWidth / window.innerHeight;
camera.updateProjectionMatrix(); // NEVER forget this
renderer.setSize(window.innerWidth, window.innerHeight);
});
Symptom 9: Transparent Object Rendering Issues
Transparent objects render in the wrong order (back-to-front sorting fails).
Fix A: renderOrder
// Force specific rendering order
backgroundMesh.renderOrder = 0;
transparentMesh.renderOrder = 1;
frontMesh.renderOrder = 2;
Fix B: depthWrite
const material = new THREE.MeshStandardMaterial({
transparent: true,
opacity: 0.5,
depthWrite: false // prevents transparent objects from writing to depth buffer
});
Fix C: alphaTest instead of transparency
For textures with hard alpha edges (foliage, fences):
const material = new THREE.MeshStandardMaterial({
map: leafTexture,
alphaTest: 0.5, // discards fragments below threshold
side: THREE.DoubleSide
// NEVER set transparent: true for hard-edge alpha -- use alphaTest instead
});
Common Console Warnings
| Warning | Cause | Fix |
|---|---|---|
THREE.WebGLRenderer: Texture is not power of two |
NPOT texture with repeat wrapping | Use power-of-two textures or ClampToEdgeWrapping |
THREE.WebGLProgram: shader error |
GLSL compilation failure | Check custom shader code for syntax errors |
THREE.PropertyBinding: Can not bind to... |
Animation targets missing property | Ensure skeleton/morph targets match the animation clip |
THREE.BufferGeometry: .addAttribute() removed |
Using deprecated API | Use setAttribute() instead |
GL_INVALID_OPERATION: Feedback loop |
Reading from a texture that is also a render target | Use separate textures for reading and writing |
Reference Links
- references/methods.md -- Fix-related API signatures
- references/examples.md -- Complete fix patterns
- references/anti-patterns.md -- What NOT to do
Official Sources
04 同仓库更多 Skills
frontend-slides
Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.
design-dna
Extract, define, and apply design DNA across three dimensions: design system (tokens), design style (qualitative feel), and visual effects (Canvas, WebGL, 3D, particles, shaders, scroll effects, etc.). Use this skill when: (1) a user wants to see the full 3-dimension design structure/schema, (2) a user provides images, screenshots, or URLs of reference designs and wants them analyzed into a structured JSON profile covering all three dimensions, (3) a user has a Design DNA JSON and content and wants a design generated from it, or (4) any combination of these phases. Triggers on "design DNA", "extract design style", "analyze design", "design tokens from reference", "generate design from JSON", "design system from screenshot", "design profile", "style guide JSON", "visual effects analysis", "design with effects", "3d design analysis".
wireframe
Generate JSON wireframe with HTML preview
social-publishing
Schedule and publish social media posts across 13 platforms (X, LinkedIn, Instagram, Facebook Pages, TikTok, Discord, Telegram, YouTube, Reddit, WordPress, Pinterest) via the SocialClaw API. Use when the user wants to publish, schedule, or manage social media content programmatically. Requires SOCIALCLAW_API_KEY.
hermes-tweet
Install and operate Hermes Tweet, a Hermes Agent plugin for X/Twitter research, timeline reading, tweet analysis, and approval-gated private or state-changing operations. Use this skill when installing Hermes Tweet, researching X/Twitter accounts, monitoring launch signals, investigating mentions, auditing giveaways, or preparing gated X operations. Use proactively when a Hermes Agent workflow needs current X/Twitter context. Requires XQUIK_API_KEY for read and action tools.
refactoring-ui
Audit and fix visual hierarchy, spacing, color, and depth in web UIs. Use when the user mentions "my UI looks off" (or amateur/unprofessional), "fix the design", "Tailwind styling", "color palette", "visual hierarchy", "design system", "spacing scale", or "component styling". Also trigger when building consistent design tokens, creating dark mode themes, improving data-visualization clarity, or polishing UI details before launch. Covers grayscale-first workflow, constrained design scales, shadows, and component styling. For typeface selection, see web-typography. For usability audits, see ux-heuristics.