Animation will not load

The canvas is blank. The animation never appears. The console may or may not have an error.

Use this when

• The <canvas> is in the DOM, but nothing renders.
• onLoadError fires.
• DevTools console mentions 404, CORS, WASM, or CSP.

What you need

• DevTools open (Console + Network tabs).
• The exact URL your code uses for the .riv file.
• The handoff.md from Lupian.

Run through this checklist in order

1. Is the .riv URL reachable?

In DevTools → Network tab, reload the page and find the .riv request.

• Status 200 → file is being served. Continue to step 2.
• Status 404 → wrong path. Fix the src value. Watch for:
  • Leading slash vs no slash (/animations/hero.riv vs animations/hero.riv).
  • Filename typos / case mismatches (Linux/macOS hosts are case-sensitive).
  • Files in public/ are served from the root, not from /public/.
• Status 403 → permission issue on your host (private bucket, missing role, expired signed URL).
• No request at all → your JS errored before calling new Rive(...). Check the Console.

2. Are CORS headers present?

If the .riv is on a different origin than the page:

• Look for Access-Control-Allow-Origin in the response headers (Network → click the .riv request → Headers).
• A console message that includes "blocked by CORS policy" confirms this.

Fix: add CORS to the host serving the .riv. See Hosting assets & CORS for per-host instructions.

3. Is WASM allowed by CSP?

If your site sets a Content Security Policy header:

• Console error mentions wasm, WebAssembly.instantiate, or unsafe-eval.

Fix: add 'wasm-unsafe-eval' to script-src:

script-src 'self' 'wasm-unsafe-eval';

4. Is the runtime package loading?

• Console error like Failed to fetch for a @rive-app/... URL → CDN/network issue or a typo in the import URL.
• Using esm.sh and the page is behind a strict offline/intranet → the CDN is unreachable. Self-host the runtime or use npm.

5. Is onLoadError firing?

Add a handler if you do not already have one:

new Rive({
  src: "/animations/hero.riv",
  canvas,
  autoplay: true,
  stateMachines: "State Machine 1",
  onLoad:      () => console.log("Rive loaded OK"),
  onLoadError: (err) => console.error("Rive load error:", err),
});

Common onLoadError causes:

• Corrupted .riv — re-download from the original handoff.
• Manually set canvas.width / canvas.height — this resets the rendering context. Remove any <canvas width="..." height="..."> attributes and let CSS size it.
• Wrong package for the file — canvas-lite cannot load .riv files that use text, audio, or scripting. Switch to @rive-app/webgl2.

6. Is the canvas actually in the DOM at the right time?

• React: are you calling getElementById from a server component or before the canvas mounts?
• Framer: design-canvas (RenderTarget.canvas) has no WebGL — see Framer recipe.
• SSR frameworks: the runtime must run client-side. Use "use client" or dynamic(..., { ssr: false }).

7. Test it on demo.lupian.studio

If your exact .riv file plays at demo.lupian.studio, the file is fine. The issue is in your environment (hosting, CSP, package).

Common mistakes

• <canvas width="500" height="500"> in the HTML. Remove the attributes — they reset the rendering context. Size with CSS instead.
• src pointing to a Google Drive / Dropbox share URL. These return HTML, not the binary .riv. Host the file on a real static origin.
• Working .riv URL in a browser tab, broken inside the page. That is CORS. Fix the response headers.
• useRive returning null and never updating. Make sure the component file has "use client" (Next App Router) or is dynamic-imported with ssr: false.

If stuck, send this to Lupian

• The exact .riv URL.
• Screenshots of the Network tab (the .riv row, including Headers) and Console.
• The framework you are using.
• See Ask Lupian for help.

Related

• Hosting assets & CORS
• Wrong size or blurry
• State machine not working