Quick checklist

1. Open the .riv file URL directly in your browser. If it 404/403s, fix the path/permissions first.
2. Make sure your page is HTTPS and your .riv URL is also HTTPS (mixed-content can block loading).
3. Give the Rive container an explicit width and height (blank embeds are often zero-height).
4. Confirm your artboard and state machine names match exactly (spelling and case matter).
5. Check browser console errors (blocked requests, CORS, script errors, wrong input name/type).

Most common problems and fixes

• Nothing shows up (blank canvas)
  • Set an explicit container height (for example 300px).
  • Confirm the file URL is accessible and returns HTTP 200 (not an HTML error page).
  • Try rendering the default artboard first (without specifying artboard/state machine) to confirm the file loads.
• Animation shows but sizing is wrong (cropped, stretched, tiny)
  • Adjust fit/alignment options (contain/cover/fitWidth/fitHeight depending on the runtime).
  • Ensure your container size matches how you want it displayed.
  • If the artboard bounds are unusual, consider fixing bounds in the Rive editor and re-exporting.
• State machine inputs or triggers don’t work
  • Verify you are using the correct state machine name (exact match).
  • Verify the input name (exact match) and input type (trigger, boolean, number).
  • Make sure your code calls the input after the file is loaded and the state machine is initialized.
  • Check you’re targeting the correct artboard if the file has multiple artboards.
• Click/tap interactions don’t respond
  • Confirm nothing is overlaying the canvas (transparent divs, z-index layers, pointer-events).
  • Ensure the canvas/container allows pointer events.
  • On mobile, test tap areas and ensure the canvas has a stable size (layout shifts can break expected coordinates).
• Works locally but not on your website
  • CORS: if the .riv file is hosted on another domain, the server may block requests. Host it on the same domain or allow your origin.
  • Caching: if you replaced a file but see old behavior, hard refresh and confirm cache headers.
  • Content security policy (CSP): a strict CSP can block the runtime or file loading.
• Loads intermittently or fails sometimes
  • Use a stable CDN or ensure your server responds quickly and consistently.
  • Avoid loading many large animations at once; stagger initialization.
  • Confirm you are not initializing the same canvas multiple times (double-mount issues).

Debugging steps

1. Open DevTools → Network and reload.
2. Click the .riv request and confirm status 200 and a reasonable file size.
3. Open DevTools → Console and look for errors related to loading, state machines, or input names.
4. Temporarily remove custom artboard/state machine settings and load the default to isolate naming issues.
5. If inputs don’t work, log available state machines and inputs from the runtime (if your integration supports it).

Tips for reliable embeds

• Use consistent, simple names for artboards and inputs (avoid special characters).
• Initialize Rive after the container has its final size (especially if inside tabs/modals).
• For responsive layouts, test resize behavior and re-layout if your runtime requires it.
• If you need multiple animations on one page, load only what’s visible first.

Performance tips

• Lazy-load below-the-fold animations.
• Pause or stop animations when offscreen (IntersectionObserver) and resume when visible.
• Avoid running many state machines simultaneously unless necessary.

When to contact the author

If the file loads but the animation looks broken, missing layers, or behaves differently than expected, it’s often an export/design issue.