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
• Use the 2.39.2 default to preserve the Rive Editor-authored positions; choosing Latest or 2.40.0 is an explicit opt-in and shows a warning

The Finder icon did not change

• The 2.4.3 UTI and icon declarations require the signed installed app to replace the older bundle and launch once
• Use Finder's Open With menu to select Rive Animation Viewer for .riv files
• Finder and Launch Services may retain cached document artwork until the app has launched and the folder is reopened

The Windows .riv icon did not change

• Older Windows installs may point Rive File\DefaultIcon at the application executable instead of the dedicated document icon
• The 2.4.3 release bundles RiveFileIcon.ico, rewrites that value during NSIS install/update, and notifies Explorer
• 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 2.4.1 reports that the bundled sidecar is missing, update to 2.4.2 or later; reinstalling 2.4.1 does not repair its path-resolution regression

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.