mcpField
B
binlog-failure-analysis

binlog-failure-analysis

github.com/dotnetDevelopment5.8k3.7k installsUpdated 1d ago
Repository

About binlog-failure-analysis

A skill for diagnosing MSBuild failures from `.binlog` files, aimed at developers investigating build errors and warnings. It prioritizes structured queries through the bundled binlog MCP server, with text-log replay as a fallback.

Key features

  1. 01Inspect errors and warnings
  2. 02Query properties, items, and evaluation
  3. 03Examine targets and embedded files
  4. 04Replay binlogs to text logs

Use cases

  1. 01Trace the cause of a failed MSBuild build
  2. 02Inspect project data captured in a binlog
  3. 03Continue diagnosis when MCP is unavailable

MCP support

Uses the bundled `Microsoft.AITools.BinlogMcp` server in the `binlog` namespace to query `.binlog` files. A text-log replay workflow is provided when the server is unavailable.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/dotnet/skills --skill binlog-failure-analysis

After installing, type/binlog-failure-analysisin Claude Code to confirm it loaded.

Details

From the project README

Analyzing MSBuild Failures with Binary Logs

This skill diagnoses MSBuild build failures from a .binlog file. The preferred path uses the binlog MCP server (Microsoft.AITools.BinlogMcp, exposed under the binlog MCP namespace) which is bundled with this plugin. If the MCP server is not available, use troubleshoot-binlog-mcp to diagnose startup when repair is wanted. If repair is blocked, declined, or unnecessary for this task, continue with the binlog replay workflow at the bottom.

Primary workflow — binlog MCP

The MCP server exposes structured tools for inspecting a .binlog without parsing text logs. Call them directly instead of replaying the binlog to a text file. Call tools/list for the MCP first if you are unsure which tools are available.

Important constraints:

  • The .binlog file is a binary format — do NOT try to cat, head, strings, or read it directly. Use only the MCP tools to query it.
  • The original source/project files might or might NOT be available on disk. Project files (.csproj, .props, .targets, App.config, etc.) - if you cannot locate them on disk, they can only be read from within the binlog via MCP tools (e.g., embedded/source file retrieval).
  • Synthesize findings as you go. Do not spend all available time investigating — once you have enough evidence, present your conclusions. A partial answer with clear reasoning is better than timing out mid-investigation.

Use the available MCP server tools to query the binary log for:

  • Build errors and warnings
  • MSBuild properties and their values
  • MSBuild items (PackageReference, ProjectReference, etc.)
  • Project evaluation data
  • Target execution details
  • File contents embedded in the binlog

Fallback workflow — text-log replay (when MCP is unavailable)

Use this only when the MCP server cannot be started (for example, on an older SDK or in an offline environment).

Replay the binlog to text logs
dotnet msbuild build.binlog -noconlog \
  -fl  "-flp:v=diag;logfile=full.log;performancesummary" \
  -fl1 "-flp1:errorsonly;logfile=errors.log" \
  -fl2 "-flp2:warningsonly;logfile=warnings.log"

PowerShell note: Use -flp:"v=diag;logfile=full.log;performancesummary" (quoted semicolons).

Search the text logs
cat errors.log
grep -n -B2 -A2 "CS0246" full.log
grep -i "CoreCompile.*FAILED\|Build FAILED\|error MSB" full.log
grep 'Target "CoreCompile"' full.log | grep -oP 'project "[^"]*"'

Generating a binlog (only if none exists)

dotnet build /bl:build.binlog

Comments

Markdown supported