Graphics Troubleshooting

Diagnose and fix 3D web graphics issues fast. Organized by symptom (what you see) for rapid diagnosis.

Library Versions (2026)

• Three.js: r171+
• React Three Fiber: v9.5+
• @react-three/drei: v9.116+
• @react-three/rapier: v2+

Quick Diagnosis

Nothing Renders (Black/Empty Screen)

Check	Command/Action
Camera position	Is camera inside object? Move to [0, 0, 5]
Camera target	Is camera looking at scene? Check lookAt
Object scale	Is object too small/large? Check scale isn't 0
Lights	Are there any lights? Add <ambientLight />
Material	Using MeshStandardMaterial without lights?
Render loop	Is animate() being called?
Canvas size	Is container height 0? Check CSS
WebGPU support	Browser support? Check console for errors

R3F Minimum Visible Scene:

<Canvas>
  <ambientLight intensity={0.5} />
  <directionalLight position={[5, 5, 5]} />
  <mesh position={[0, 0, 0]}>
    <boxGeometry />
    <meshStandardMaterial color="red" />
  </mesh>
</Canvas>

Vanilla Three.js Minimum Scene:

import * as THREE from 'three/webgpu'

const scene = new THREE.Scene()
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000)
camera.position.z = 5

const renderer = new THREE.WebGPURenderer({ antialias: true })
await renderer.init()
renderer.setSize(window.innerWidth, window.innerHeight)
document.body.appendChild(renderer.domElement)

// Add light - required for Standard materials
scene.add(new THREE.AmbientLight(0xffffff, 0.5))
scene.add(new THREE.DirectionalLight(0xffffff, 1))

// Add visible object
const mesh = new THREE.Mesh(
  new THREE.BoxGeometry(),
  new THREE.MeshStandardMaterial({ color: 'red' })
)
scene.add(mesh)

function animate() {
  renderer.render(scene, camera)
}
renderer.setAnimationLoop(animate)

Object Renders But Looks Wrong

Symptom	Cause	Fix
All black	No lights	Add ambient + directional light
Flickering faces	Z-fighting	Increase camera near, offset overlapping geometry
Inside-out	Inverted normals	material.side = THREE.DoubleSide or fix in Blender
Pixelated edges	Low DPR	renderer.setPixelRatio(Math.min(devicePixelRatio, 2))
Washed out colors	No tone mapping	renderer.toneMapping = THREE.ACESFilmicToneMapping
Colors look wrong	Color space	renderer.outputColorSpace = THREE.SRGBColorSpace
Texture blurry	Filtering	texture.minFilter = THREE.LinearMipmapLinearFilter
Texture stretched	Wrong UVs	Check UV mapping in Blender, use texture.repeat

Performance Issues

Symptom	Diagnosis	Target	Fix
Low FPS (<30)	Check renderer.info.render.calls	<100 draw calls	Use InstancedMesh, merge geometries
Stuttering/hitching	GC pauses	Avoid allocations	Object pooling, reuse Vector3s
Memory growing	Check renderer.info.memory	Stable	Call .dispose() on removal
Slow initial load	Large assets	<5MB total	Compress with Meshopt, resize textures
Slow on mobile	Too many triangles	<100K	Simplify geometry, use LOD

Quick Performance Check:

// Add to console or scene
console.log('Draw calls:', renderer.info.render.calls)
console.log('Triangles:', renderer.info.render.triangles)
console.log('Geometries:', renderer.info.memory.geometries)
console.log('Textures:', renderer.info.memory.textures)

See references/performance.md for detailed profiling.

Loading Failures

Error	Cause	Fix
404 Not Found	Wrong path	Check file exists, use absolute path from public
CORS error	Cross-origin	Serve from same origin or configure CORS headers
"Unexpected token"	Wrong file format	Ensure file is valid GLTF/GLB
Draco decode error	Missing decoder	Set dracoLoader.setDecoderPath('/draco/')
KTX2 decode error	Missing transcoder	Set ktx2Loader.setTranscoderPath('/basis/')
"Invalid glTF"	Corrupted file	Validate at https://gltf.report
Model invisible	Wrong scale	Check scale (Blender default: 1 unit = 1 meter)

Loader Setup Pattern:

import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js'
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js'
import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js'
import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js'

const loader = new GLTFLoader()

// Draco (for Draco-compressed models)
const dracoLoader = new DRACOLoader()
dracoLoader.setDecoderPath('https://www.gstatic.com/draco/versioned/decoders/1.5.6/')
loader.setDRACOLoader(dracoLoader)

// Meshopt (for Meshopt-compressed models)
loader.setMeshoptDecoder(MeshoptDecoder)

// KTX2 (for Basis Universal textures)
const ktx2Loader = new KTX2Loader()
ktx2Loader.setTranscoderPath('https://cdn.jsdelivr.net/npm/three@0.171.0/examples/jsm/libs/basis/')
ktx2Loader.detectSupport(renderer)
loader.setKTX2Loader(ktx2Loader)

See references/loading.md for more patterns.

Physics Issues (@react-three/rapier)

Symptom	Cause	Fix
Objects fall through floor	Missing collider	Add <RigidBody type="fixed"> to ground
Objects stuck in air	Wrong body type	Use type="dynamic" for moving objects
Jittery movement	High velocity + low mass	Increase mass or reduce forces
Tunneling (fast objects pass through)	CCD disabled	Enable ccd={true} on fast bodies
Collider wrong shape	Auto-collider mismatch	Use explicit <CuboidCollider> etc.
Physics not updating	Wrong loop	Check updateLoop prop on <Physics>

Minimum Physics Setup:

import { Physics, RigidBody } from '@react-three/rapier'

<Physics gravity={[0, -9.81, 0]} debug>
  {/* Ground - fixed, doesn't move */}
  <RigidBody type="fixed">
    <mesh position={[0, -1, 0]}>
      <boxGeometry args={[10, 0.5, 10]} />
      <meshStandardMaterial />
    </mesh>
  </RigidBody>

  {/* Falling object - dynamic */}
  <RigidBody type="dynamic">
    <mesh>
      <sphereGeometry />
      <meshStandardMaterial />
    </mesh>
  </RigidBody>
</Physics>

Shader/Material Errors

Error	Cause	Fix
"X is not defined" in shader	Missing uniform/varying	Declare all variables
Black material	Shader compile error	Check console for GLSL/WGSL errors
Material not updating	Missing needsUpdate	Set material.needsUpdate = true
TSL error	Wrong import	Use import { x } from 'three/tsl'
NodeMaterial black	Missing colorNode	Set material.colorNode = ...

TSL Debug Pattern:

import { color, uniform } from 'three/tsl'

// Start simple, add complexity
const material = new THREE.MeshBasicNodeMaterial()
material.colorNode = color(0xff0000) // Should be red

// If this works, add your custom logic incrementally

Related Skills

When you need...	Use skill
Optimize assets before loading	asset-pipeline-3d
Build scenes with vanilla Three.js	threejs
Build scenes with React	react-three-fiber

Reference Files

• references/visual-bugs.md - Z-fighting, clipping, shadow artifacts, transparency issues
• references/performance.md - Profiling, optimization, memory management
• references/loading.md - Asset loading, decoder setup, CORS, caching