Diagnose problems in your build

Diagnosing and fixing build problems is a regular task in software development. Team Foundation Build provides tools to help you debug and resolve problems such as:

• Failed or partially successful builds

• Exceptions, errors, or warnings

• Unexpected events or results

What do you want to do?

• Determine why a build is not running

• Look for information about a problem in the build results window

• Request and view diagnostic logs

• Check your build system and debug your build process

• Get more tips

Required permissions

You must be a member of the Windows Administrators group on the build server, and a member of the Project Collection Build Administrators group on your team project collection. See Pernission reference for Team Foundation Server.

Determine why a build is not running

If the build is next in the queue but is still not running, make sure the build controller and at least one of its build agents are Available and Enabled. If your build process has build agent filters, make sure a build agent that meets the criteria is Available and Enabled. See Manage your build system, Specify Which Build Agents Process Your Build, and Deploy and configure build agents.

Look for information about a problem in the build results window

If your build is running, stuck at some part of the process, or completed, then you can get more information about the problems in the build results window. Choose View Log to display more detailed information:

• To skip directly to problems in the build, choose Next Error or Next Warning.

• Wherever you see instances of an MSBuild Log File link, choose it to get more detailed information about events that occurred when the MSBuild activity compiled your code and performed other tasks.

• You can copy information and, if you want, share it with people who can help you resolve the problems. Select specific passages in the log or open a context menu from anywhere in the log and then choose Select All. You can then open a context menu and choose Copy to copy the text to the clipboard.

View diagnostic logs

If you still do not have enough information to diagnose the problem, you can view more detailed diagnostic logs. In the build results window, choose Diagnostics, and then:

• If the build is completed, choose Final logs as of date and time.

• If the build is not yet completed, choose Request Logs.

  

  The system assembles the logs.

  When the logs are ready, choose Diagnostics, As of date and time for User who requested the log.

If your build stages output to a UNC path drop folder, then the system opens a drop folder sub-folder that contains the diagnostic logs. After you open the drop folder or download the .zip file, you can view one of the following logs:

• From the build controller: ActivityLog

• From each build agent that participated in the build: ActivityLog.AgentScope.Build_Agent_ID

• For each solution compiled by the MSBuild activity: Solution_Name

The best way to view these logs is to copy them to your dev machine and open them from there.

Check your build system and debug your build process

Some problems can be caused by your on-premises build system.

Check your build system components

Make sure that your build server, controller, and agent are correctly configured. See Deploy and configure a build server, Deploy and configure a build controller, and Deploy and configure build agents.

Log on to the build server and confirm that it is functioning correctly. You can also view detailed diagnostic data on the build server. See Manage your build system.

Debug a build process on the build server

To diagnose problems caused by custom build process activities, or by uncaught exceptions, try to debug the build process on your build server.

1. Log on to the build server.

2. Run Visual Studio as an administrator.

3. In Visual Studio, from the menu bar, choose Tools, Attach to Process.

4. On the Attach to Process dialog box:

   1. Select Show processes from all users.

   2. Select TFSBuildServiceHost.exe.

   3. Choose Attach.

5. From menu bar choose Debug, Exceptions. On the Exceptions dialog box, select Common Language Runtime Exceptions. Choose OK.

6. From menu bar, choose Tools, Options. On the Options dialog box, in tree pane, select Debugging. In the General list, and clear the Enable Just My Code check box. Choose OK.

7. In Visual Studio, queue the build and make sure that it runs on a build controller and a build server that are hosted on the build server on which you have enabled the debugger.

You can now debug exceptions that are thrown during the build process, and also set breakpoints and debug your custom build process activities. See Debugging in Visual Studio.

Tips

• While you are diagnosing problems with a build process, you might save yourself and your teammates problems by pausing it until you can repair the process:

  • Edit the build definition, and then at the bottom of the General tab, choose Paused.

  • To test your fixes to the build process, select a queued build, open its context menu, and then choose Start Now.

• If you think one of your build system components might be the cause of one of the problems, you can start, stop, or restart a build server or enable or disable a controller or agent as needed. See Manage your build system.

• Frequently, while attempting to fix build process problems, you need to queue a build with the same options repeatedly to test various fixes. You can quickly retry a build:

  • From the build results window by choosing Actions, Retry Build.

  • From the Builds page in Team Explorer or from Build Explorer by selecting a completed build, opening its context menu, and choosing Retry Build.

• Are you using the Hosted Build Controller? See Use the Hosted Build Controller.