Diagnosing Bevy Asset Hot‑Reload Failures on Desktop: A Step‑by‑Step Guide

Problem Overview

In a Bevy 0.10+ desktop build you might notice that changing a PNG, TTF, or JSON asset on disk does not reflect in the running game. In extreme cases the engine stalls or crashes after a file modification. The symptom set is:

• Textures, fonts, or other assets load correctly on the first run but never refresh.
• Console logs show no "Asset hot‑reload detected" messages.
• Repeated edits cause memory usage to grow without bound.

These failures usually stem from the asset server’s file‑watcher, permission misconfiguration, or build‑time hot‑reload disabling. The following diagnostic guide helps you isolate the root cause and apply the appropriate fix.

Common Causes

Cause	Typical Symptoms	Why it Happens
File‑watcher not firing	No reload logs; assets stay stale.	OS limits (inotify, ReadDirectoryChangesW) or missing permissions.
Hot‑reload disabled in release build	Assets never refresh; no logs.	Bevy disables the watcher in release by default.
Path or permission misconfiguration	Assets load once, then fail to reload; sometimes crash.	Long Windows paths or read‑only directories.
Asset handle leaks	Memory grows with each edit.	Handles not dropped, causing the server to keep old versions alive.

Diagnostic Checklist

1. Confirm Build Profile
   • Run cargo build --profile dev or cargo run (dev by default).
   • Check Cargo.toml for [profile.release] overrides that might disable hot‑reload.
2. Verify File‑Watcher Logs
   • Start the game with RUST_LOG=info cargo run (Linux/macOS) or set RUST_LOG=info & cargo run (Windows).
   • Look for lines like info: Asset hot‑reload detected: sprite.png.
   • If absent, the watcher is not reporting events.
3. Check OS‑Specific Limits
   • Linux: cat /proc/sys/fs/inotify/max_user_watches. If the value is lower than the number of watched directories, increase it:

     # sudo sysctl -w fs.inotify.max_user_watches=524288
     

   • Windows: Ensure the asset path is < 255 characters and the user has read permissions.
4. Validate Asset Permissions
   • Run ls -l sprite.png (Linux/macOS) or icacls sprite.png (Windows) to confirm read access for the current user.
5. Inspect Asset Server Thread
   • Use Bevy’s profiler or cargo run --features bevy/profiling to confirm the asset server thread is alive.
6. Monitor Memory Growth
   • Start the game with cargo run --release and track free -m (Linux) or Task Manager (Windows).
   • If memory rises steadily after each asset edit, suspect handle leaks.

Fixes & Workarounds

1. Enable Hot‑Reload in Release
   • Add to Cargo.toml:

     [profile.release]
     debug = true
     opt-level = 3
     

   • Or set the environment variable BEVY_HOT_RELOAD=1 before running.
2. Increase Inotify Watches
   • Run sudo sysctl -w fs.inotify.max_user_watches=524288 and add to /etc/sysctl.conf for persistence.
   • Restart the game and confirm reload logs appear.
3. Shorten Asset Paths on Windows
   • Move the project to a shorter root (e.g., C:/dev/bevy) or use the subst command to map a drive letter to a deep path.
   • Verify that the path length < 255 characters.
4. Clean Asset Handles
   • When reloading assets manually, drop the previous Handle from the Assets resource:

     let old_handle = asset_server.load("sprite.png");
     // ... use old_handle
     assets.remove(old_handle);
     

   • Consider using AssetServer::reload_asset(&mut assets, &mut asset_server, path) (available in newer Bevy releases) to replace the handle automatically.
5. Check Custom Asset Server Configurations
   • If you replaced the default AssetServer with a custom implementation, ensure it forwards file‑watch events to the AssetServer or implements its own hot‑reload logic.

Escalation & Further Investigation

If after applying the above steps hot‑reload still fails, consider the following:

• Run the game under a debugger and set a breakpoint on AssetServer::handle_watcher_event to confirm the event is received.
• Inspect the bevy::asset::AssetServer::watch configuration in your AppBuilder to ensure the watch_delay is not set to an excessively high value.
• Check for third‑party crates that might interfere with the standard file‑watcher (e.g., notify versions).
• Open an issue on the Bevy GitHub repository with a reproducible minimal example and the diagnostic log output.

Preventive Tips

To avoid hot‑reload headaches in future projects:

• Keep asset directories shallow and under 10 levels deep.
• Use a consistent OS‑agnostic path separator (/) in code to avoid Windows path issues.
• Regularly run cargo clean before large asset changes to reset the asset cache.
• Add a post‑build script that verifies BEVY_HOT_RELOAD is set for dev builds.

By following this diagnostic flow, you can pinpoint whether the problem lies with the file watcher, permissions, build configuration, or asset handle management, and apply the precise fix without unnecessary trial and error.