Diagnose Build Problems

  • Article

Diagnosing and fixing build problems is a regular task in software development. Team Foundation Build provides tools to help you diagnose 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

  • Resolve problems when using the Hosted Build Controller

  • Request and view diagnostic logs

    • Get diagnostic logs when you are using an on-premises build controller

    • Get diagnostic logs when you are using the Hosted Build Controller

    • View the 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 Team Foundation Server Permissions.

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:

  • Choose Next Error or Next Warning to skip directly to problems in the build.

  • 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 shortcut menu from anywhere in the log and then choose Select All. You can then open a shortcut 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.

Get diagnostic logs when you are using an on-premises build controller

When you host an on-premises build controller, the diagnostic logs are stored in a drop folder. 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.

    Retrieving diagnostic log

    The system assembles the logs.

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

The system opens a drop folder sub-folder that contains the diagnostic logs.

Note

If you are using Visual Studio 2010, the Diagnostics menu is not shown on the build results window, but you can still view the diagnostic logs in the drop folder when the build is completed.

Get diagnostic logs when you are using the Hosted Build Controller

When you use the Hosted Build Controller, we recommend that you select Copy build output to the server for the staging location. In this case, the diagnostic logs are stored in TFS and you can view them and download them from your web browser.

In the build results window, choose Actions, Open in Browser, and then in the build results in the web browser, choose diagnostics. You can then choose View logs to open a menu from which you can choose the log you want to view, or to download all the logs in a .zip file.

View 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.

Tip

Try deploying your dev machine as a build server so that you can more easily get direct access to the environment in which the build process is running. See Deploy and Configure a Build Server.

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

  • Tip 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.

    • While the build definition is paused, to test your fixes to the build process, select a queued build, open its shortcut menu, and choose Start Now.

  • Tip 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.

  • Tip 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 shortcut menu, and choosing Retry Build.