Troubleshooting

Problem-first index. Open the page that matches your symptom.

Use this when

Something is wrong and you need to identify it fast.

What is happening?

Nothing shows up at all

• Page loads, but the canvas is blank or the slot is empty.
• DevTools console shows an error or a 404, or sometimes nothing at all.

→ Animation will not load (404, CORS, WASM, CSP, file path mistakes)

It renders, but the size or sharpness is wrong

• Animation appears at the wrong size, stretched, squished, or clipped.
• Animation looks pixelated, blurry, or low-res on Retina/4K.
• Animation flickers or jumps in size on window resize.

→ Wrong size or blurry (canvas CSS, DPR, resizeDrawingSurfaceToCanvas)

It plays, but does not respond to interaction

• Hover/click does nothing.
• A button in the animation visibly clicks but your code does not get the event.
• stateMachineInputs(...) returns an empty array.

→ State machine not working (wrong names, wrong artboard, wrong input type)

One animation is fine, but pages with several break

• First few animations work, then later ones go black.
• A console warning about WebGL context lost.
• Memory grows when navigating between pages with animations.

→ Multiple animations on a page (offscreen renderer, cleanup, WebGL context limits)

Quick triage checklist

Before opening any page above, run through this once:

1. Open the browser DevTools console. Any errors? Screenshot them.
2. Open the Network tab. Does the .riv request return 200? Any CORS warning?
3. Check the names. Open handoff.md and compare every name in your code letter-for-letter, case included.
4. Confirm the runtime. @rive-app/webgl2 is the default safe pick for Lupian deliveries.
5. Try the same file on demo.lupian.studio. If it works there, the issue is on your site, not the file.

If stuck, send this to Lupian

• The symptom (1 sentence).
• The page URL or repo.
• Console + Network screenshots.
• The handoff.md you received.
• See Ask Lupian for help for the full intake list.