Troubleshooting

The canvas is blank

• Give the viewer or parent a non-zero height.
• Check onError and browser console.
• Verify the model URL and CORS headers.
• Increase the camera far plane for very large scenes.
• Call fitCamera() after loading.

GLTF loads without textures

• Deploy referenced images at the expected relative paths.
• Set resourcePath when dependencies use another base.
• Inspect network requests for 404 or CORS failures.

Draco model fails

• Copy decoder files to the public directory.
• Pass the directory through dracoDecoderPath.
• Confirm the path works from the production deployment base.

Model rotates around empty space

Use the bounds-center, exact, or picked pivot workflow. Preserve visual position when changing an already-positioned model.

Sequence camera jumps

• Ensure camera target is captured with position.
• Sort or inspect duplicate-time keyframes.
• Add intermediate rotation keyframes.
• Disable user controls during playback.

Replacement texture does not appear

• Confirm its export has replacement: true.
• Map the exact exported filename in textureUrls.
• Handle onTextureError.

Normals are slow

Use selected scope and disable the helper after diagnosis.