Troubleshooting Connecting to Xamarin Mac Agent

Couldn’t connect to mac.local. Please try again. This problem appears more than I would like and it is due to a variety of issues. These normally occur after upgrades or setting up your Mac Build Host for the first time.macconnected

Connecting To The Mac Agent

You have a Mac setup and Visual Studio running and you are wanting to connect to your Mac Build host but it will not connect.

If you are failing to connect to your Mac you will experience either a spinner that disappears and gives you no warnings, or a dialog box, with an error message, that usually is hiding the root cause of your issues.


Connection Errors

Error: Couldn’t retrieve SSH Fingerprint. Please ensure the Mac is reachable and Remote Login is enabled.


Steps to Resolve

  1. Can you ping the Mac? If not, you have a network issue.
  2. Is Remote Login enabled. Follow the instructions on how to enable it.

Configuration Errors

Error: Couldn’t connect to MacServer.local. Please try again.

Quick Checklist

  1. Have you installed XCode on your Mac?
  2. Do you have the latest version of XCode?
  3. Have you opened up XCode on your Mac to agree to the terms and conditions. You must do this on first install, or on each upgrade that requires it.
  4. Have you installed Xamarin on your Mac?
  5. Are the Xamarin Versions the same on your PC and Mac?

View Logs

If you are still having issues, we need to delve into the logs. Go to Help > Xamarin > Open Logs…


A folder window will open. Open the latest log text file and see what errors have been occurring. I have included some that I have seen and their solution below.

Error: The user ‘<username>’ must be logged in on the mac in order to start the agent.

Solution: You must be logged into the Mac under the same username that you are trying to connect to the Mac agent.

Error: Renci.SshNet.Common.ScpException: scp: /tmp/ Permission denied

Solution: A reboot of your Mac, will resolve this permission error.

If you come across any different errors and have a solution, please comment below.

Stability Issues

While using the Mac Agent, you may come across build errors. Looking at the logs you will find the Mac Agent was disconnected and you have to connect again. While annoying, the fix is to reconnect again. Some tips to keep the connection active for a greater amount of time includes:

  1. Ensure you have the latest Xamarin version. Stability updates are included every now and again.
  2. Ensure you have the same Xamarin version on both the PC and Mac. While they can sometimes work with different versions, it can lead to degraded performance.
  3. Use Ethernet and not WiFi. It results in a far better experience overall.