Skip to content
RAVDocumentation

Troubleshooting

Animation won't load

  • Verify the file is a valid .riv file (not a .rev project file)
  • Check the event console for error messages
  • Try switching between Canvas and WebGL2 renderers
  • Ensure the file isn't corrupted — re-export it from the source project or obtain a fresh .riv export

Configuration won't apply

  • Ensure you're writing valid JavaScript syntax (not JSON)
  • Check the red error banner for syntax error details
  • Errors auto-dismiss after 5 seconds; check the console for persistent errors

ViewModel controls missing

  • The animation must have ViewModelInstances defined in the Rive Editor
  • Use autoBind: true to bind the default instance automatically, or choose an explicit instance from the VM Instance selector
  • The selector stays populated for a single default or unnamed instance; if it is empty, reload the file and inspect the event console
  • Try reloading the animation

Nested images are displaced

  • Check the runtime version in the bottom strip or Settings
  • Web 2.40.0 / runtime-v0.1.271 has a confirmed nested, data-bound image double-offset in both Canvas and WebGL2
  • Latest (auto) is the default. If a particular runtime shifts authored positions, pin 2.39.2; the known 2.40.0 layout risk remains labeled

The Finder icon did not change

  • Install the signed RAV app in /Applications and launch it once
  • Open RAV Settings and check Default .riv App; it names the application macOS currently resolves for .riv files or another installed RAV copy. Use MAKE DEFAULT once, then use REPAIR ICON if Finder still shows stale document artwork
  • Finder and Launch Services may retain cached document artwork until the app has launched and the folder is reopened
  • Default-app and document-icon registration do not repair Quick Look previews, which are supplied by a separate system extension

The Windows .riv icon did not change

  • Run the RAV installer again so it can register the dedicated RiveFileIcon.ico document icon and notify Explorer
  • Check that Rive File\DefaultIcon points to the installed document icon rather than the application executable
  • Verify the installed icon path exists before clearing Explorer's icon cache

Desktop build fails

  • Run rustup update to ensure latest Rust toolchain
  • Check npm run tauri info for missing dependencies
  • On macOS, verify Xcode Command Line Tools are installed

MCP not connecting

  • Open the MCP Setup dialog to verify the sidecar path and port
  • Check the MCP indicator: green means ready, blue means a command arrived recently, yellow means connecting, red means an error, and muted means disabled
  • Verify the server is registered: claude mcp list or codex mcp list
  • The bridge auto-reconnects — if the client started after RAV, wait a few seconds
  • Change the bridge port in the MCP Setup dialog if 9274 is occupied
  • If RAV reports that the bundled sidecar is missing after an update, install the current release from GitHub, relaunch RAV, and reopen MCP Setup

Preview looks slower while recording a heavy file

  • The recorded output is complete and exact regardless of how the live preview looks while capturing
  • Live recordings (the default clock) track wall time and can report capture lag on demanding files; check the frame count and lag in the status bar
  • Offline recordings render every simulation frame exactly and never consult wall time, so they are unaffected by preview slowdown

Hidden or minimized windows

  • Desktop playback runs on the window's own animation frames; a hidden or occluded window pauses rendering and resumes automatically once it is revealed
  • Recording continues while the window is hidden or minimized — frames are still captured on schedule

Getting Help

If your issue isn't covered here, open an issue on GitHub with your OS version, RAV version, and the .riv file if possible.