Troubleshooting
Fix the common problems: Node, Tailscale, paths, and peers.
Work through these in order. Most issues come down to Node, Tailscale, or the project path.
"Node.js not found" when launching
Cause: Node is not installed, or the terminal has not picked up the PATH.
- Run
node --versionin a terminal. - If it fails, install Node LTS from nodejs.org.
- Close and reopen the terminal (and the launcher) so PATH refreshes.
"relay error, retry in 5s" repeatedly
Cause: the agent cannot reach the relay introducer on 100.123.2.61:6668.
- Is Tailscale connected? Open the app and confirm you are logged in.
- Run
tailscale statusand confirm the relay box's IP is reachable. - From a terminal run
ping 100.123.2.61. No reply = not on the tailnet / relay offline. - Make sure
MUE_RELAY_HOSTandMUE_RELAY_PORTmatch the team values.
Files are not syncing
- Is the agent window open on both ends? Closing it stops syncing.
- Are you on the same Tailscale network as the other artist?
- Confirm each agent prints
peer connected <name>. If not, the peers cannot reach each other on port 6670. - Is the file in an ignored folder? Check What Gets Synced. Build output is skipped by design.
- Is
MUE_CONTENT_DIRcorrect on both machines? It must be the project root, and relative paths must match.
Files sync but never appear in my editor
- Confirm the file landed in your project folder on disk.
- If UE was closed when it landed, restart the editor or use the asset download / hot-reload plugin.
- Check
Content/.mue-sync-incoming/changed.jsonlon your machine for appended markers.
Hash mismatch / "synced in" then file disappears
Cause: the file changed while it was being transferred (rare), or the disk is too slow. The agent verifies each file and drops corrupted ones for safety. Just save the file again and it retransmits.
Agent crashes or exits unexpectedly
- Reboot your machine and relaunch.
- Check the terminal for a stack trace and note the exact line.
- Make sure the project path has no trailing backslash problems; use forward or clean Windows paths.
Everything looks fine but it is slow
- Big files stream over your local network speed. For very large assets, expect a few seconds.
- Make sure no other heavy traffic is saturating your connection.
- Reduce catch-up churn by touching large folders less often; the 10-minute catch-up window resends recent files on reconnect.
Still stuck? Check the agent window output, note the lines around
the error, and report them to your team admin. The [mue-sync ...] prefix makes logs easy to
grep.