What to do when your TFS build agent says it is ready, but the icon says it is not

When using TFS2010 It is possible for a build agent to appear to be ready (or so the status label says) but the icon stays in the off state.

This is usually due to a couple of broad categories of error, you can find out which by checking the Windows event log.

The build agent cannot communicate with the controller

In the event log you see something like

Service 'Default Agent - win7' had an exception:
Exception Message: There was no endpoint listening at http://controller.mydomain.co.uk:9191/Build/v3.0/Services/Controller/1 that could accept the message. This is often caused by an incorrect address or SOAP action. See InnerException, if present, for more details. (type EndpointNotFoundException)

This should not happen too much within a corporate LAN, though it is always worth checking to make sure any PCs firewalls are not blocking the port used by the build service (9191).

However if you are trying to use build agents that are not directly on your LAN/AD (see this lovely clear blog post on how to set up using a non-domain joined build agent) there is a good chance you will not have DNS working as expected. So make sure the controller can resolve the name of the agent and vice versa. For me this meant editing HOST files and checking name resolved with good old PING.

Custom assemblies have un-resolved dependencies

Whilst writing documentation for the community extensions for TFS build I had the this problem. I had the custom assemblies path set for the build controller. This meant when the build agent starts it downloads any custom assemblies from the specified folder. Some the community extensions assume that the build agent has features/application installed such IIS or Visual Studio. I had assumed any missing dependencies would only show up when you tried to use a community activity in a build. However, this is not the case it seems. During the agent load some checks are made. In the event log I saw errors such as

Service 'Default Agent - win7' had an exception:
Exception Message: Problem with loading custom assemblies: Could not load file or assembly 'Microsoft.VisualStudio.Shell, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a' or one of its dependencies. The system cannot find the file specified. (type Exception)

or

Service 'Default Agent - win7' had an exception:
Exception Message: Problem with loading custom assemblies: Could not load file or assembly 'Microsoft.Web.Administration, Version=7.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35' or one of its dependencies. The system cannot find the file specified. (type Exception)

To resolve these issues I installed the features and application on the agent needed by the build extensions. The other option would be remove the custom extension assemblies that had the dependencies, assuming you did not need them.

So hopefully this post should give you a pointer on fixing strange ‘has it started or not’ states that the build agent can get into