Troubleshooting

Model doesn't appear

Check the console. Open browser DevTools (F12) and look for [vitrine] messages. Common causes:

• Missing data-vitrine attribute — the <div> must have data-vitrine to be recognized
• No dimensions — the container has zero width or height. Set explicit width, height, or aspect-ratio in CSS
• CORS error — if using data-model with a direct URL, the server must send Access-Control-Allow-Origin headers. Showcase IDs (data-vitrine-id) don't have this issue
• Network error — check that the model URL is accessible and returns a valid GLB file

Model looks dark

The viewer uses environment-based lighting (HDRI). If your model appears dark:

• Check the HDRI — some presets are intentionally dim. Try switching to a brighter environment in the editor
• Check material properties — if your model's metallic value is high but roughness is low, it acts as a mirror. Make sure the environment provides something to reflect
• Add direct lights — enable key/fill/rim lights in the editor for more control

Model is oriented wrong

Vitrine handles axis conventions automatically (Y-up, Z-up). If the model still appears rotated:

• Open the model in the editor
• Adjust the orientation mapping in the settings
• Re-export from your 3D software with Y-up if possible

Viewer loads slowly

• Check file size — models over 30 MB will load slowly on mobile. See Supported Formats for optimization tips
• Enable thumbnails — server-rendered poster images give instant visual feedback while the viewer loads
• Check your connection — the WASM runtime is about 5 MB (compressed). First load downloads it; subsequent loads use the browser cache

WebGPU not working

See the dedicated WebGPU Support page for browser compatibility and how to enable WebGPU.

The viewer falls back to WebGL2 automatically. A small info icon appears in the corner when running in fallback mode.

Viewer uses too much battery

Vitrine uses reactive rendering — it only draws frames when something changes (camera movement, animations). When idle, GPU usage drops to zero.

If you notice high GPU usage:

• Auto-rotate continuously requests frames. Disable it if battery life matters
• Multiple viewers on one page multiply GPU load. Consider using thumbnail posters for off-screen viewers

Embed doesn't match editor preview

The editor and embed use the same renderer, so they should match exactly. If they differ:

• Check data-config overrides — inline config patches override the saved settings
• Check the Look — if you changed the Look after generating the embed code, the embed uses the updated Look
• Aspect ratio — the camera framing adapts to the container's aspect ratio. A different aspect ratio in the embed vs. editor will frame the model differently

Still stuck?

Reach out at [email protected] with:

• Your showcase ID or model URL
• Browser and OS version
• A screenshot or console log of the issue