Fixing a broken mutagen installation after an upgrade

If you’ve just upgraded mutagen via homebrew or some other mechanism and your syncing has completely broken hopefully this will fix the issue for you. For me, it has happened a few times but I was motivated to write down the steps to fix it after my 0.17.2 → 0.17.3 upgrade failed.

The symptoms:

  • Syncing stops (obviously)
  • mutagen sync list reports that it’s connecting but never connects


  • Initiator - the system where you run mutagen sync list
  • Backend - the system that the initiator connects to

I don’t think I can say alpha and beta here because the order could be reversed

The solution:

  • Determine which version of mutagen is on your system with mutagen --version
  • Make sure the mutagen version in your alpha and beta systems is the same (if they’re not you’ll need to download the correct agent version for whichever system is initiating the sync)
  • Stop all copies of mutagen-agent running on the backend and mutagen running on the initiator
  • Find your mutagen version in the mutagen releases page and download the version that matches the architecture of the backend system. For my M1 Mac Mini I downloaded mutagen_darwin_arm64_v0.17.3.tar.gz
  • Download the corresponding archive for the backend system and extract it. This will yield two files. mutagen (or mutagen.exe on Windows) and the mutagen-agents archive.
  • Extract the mutagen-agents archive and find the agent binary that corresponds to the architecture of the backend system. For my M1 Mac Mini I used darwin_arm64.
  • Copy the agent binary to your .mutagen/agents/VERSION/ path and rename it mutagen-agent. In my case I ended up with the file .mutagen/agents/0.17.3.
  • Restart mutagen on the initiator with mutagen sync list or whatever you normally use