MUE SyncFeaturesHow It WorksSetupDocsFAQDownload

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.

  1. Run node --version in a terminal.
  2. If it fails, install Node LTS from nodejs.org.
  3. 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.

  1. Is Tailscale connected? Open the app and confirm you are logged in.
  2. Run tailscale status and confirm the relay box's IP is reachable.
  3. From a terminal run ping 100.123.2.61. No reply = not on the tailnet / relay offline.
  4. Make sure MUE_RELAY_HOST and MUE_RELAY_PORT match the team values.

Files are not syncing

  1. Is the agent window open on both ends? Closing it stops syncing.
  2. Are you on the same Tailscale network as the other artist?
  3. Confirm each agent prints peer connected <name>. If not, the peers cannot reach each other on port 6670.
  4. Is the file in an ignored folder? Check What Gets Synced. Build output is skipped by design.
  5. Is MUE_CONTENT_DIR correct on both machines? It must be the project root, and relative paths must match.

Files sync but never appear in my editor

  1. Confirm the file landed in your project folder on disk.
  2. If UE was closed when it landed, restart the editor or use the asset download / hot-reload plugin.
  3. Check Content/.mue-sync-incoming/changed.jsonl on 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

  1. Reboot your machine and relaunch.
  2. Check the terminal for a stack trace and note the exact line.
  3. Make sure the project path has no trailing backslash problems; use forward or clean Windows paths.

Everything looks fine but it is slow

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.