Skip to content
MSBuild Binlog Failure Analysis

MSBuild Binlog Failure AnalysisSkill

by .NET Team at Microsoft
Added to Onei
MIT
Repository Docs
markdown Development

Summary

Diagnose an MSBuild build failure from a .binlog file — query the binary log through a dedicated MCP server instead of grepping console output, with a text-replay fallback.

Features

  • Routes binlog queries through the bundled Microsoft.AITools.BinlogMcp MCP server
  • Stops the agent from trying to read a binary log as text
  • Recovers project files from inside the log when they are not on disk
  • Text-replay fallback with split error, warning and diagnostic logs for offline or older SDKs
  • Includes the PowerShell quoting variant for file-logger parameters
  • Built-in stopping rule: synthesise and report rather than investigate to a timeout

Install This Skill

Add this skill to your favorite AI agent in a few steps.

Any AI agent

This skill is plain instructions — it works with any assistant that accepts custom instructions or system prompts.

  1. Copy the skill content with the button below.
  2. Paste it into your agent's instruction file or system prompt (for example AGENTS.md, .cursorrules, or a custom instructions field).
  3. Ask the agent to apply the skill whenever the task matches.

Skill Content

Markdown Content

Copy this content and use it with your preferred AI agent

---
name: binlog-failure-analysis
description: "Analyze MSBuild binary logs to diagnose build failures. USE FOR: build errors that are unclear from console output, diagnosing cascading failures across multi-project builds, tracing MSBuild target execution order, and generally any MSBuild build issues. Requires an existing .binlog file. DO NOT USE FOR: generating binlogs (use binlog-generation), non-MSBuild build systems."
license: MIT
---

# 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, fall back to 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

```bash
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

```bash
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)

```bash
dotnet build /bl:build.binlog
```

Usage Instructions

Learn how to use this skill with different AI agents.

Generic Instructions

Install the marketplace with /plugin marketplace add dotnet/skills, then install the dotnet-msbuild plugin. The skill triggers on unclear build errors, cascading multi-project failures and MSBuild target-order questions, and expects a .binlog to already exist.

Example Usage

This solution fails to build in CI but not on my machine — here's the binlog, find the project that actually broke and tell me why.

Description

When a .NET build fails across a multi-project solution, the console output is usually the least informative artefact in the room: the real error is buried under cascading failures from projects that only failed because something upstream did. MSBuild's binary log (.binlog) records the whole build — evaluation, property values, item lists, target execution order, even the contents of the project files themselves — and this official .NET skill teaches a coding agent to read it properly.

Why it needs a skill at all

A .binlog is a binary format. An agent left to its own devices will try to cat, head or strings it, get garbage, and then guess. The skill's first job is to stop that: it routes the agent to the bundled binlog MCP server (Microsoft.AITools.BinlogMcp, exposed under the binlog namespace), which offers structured queries for errors and warnings, MSBuild properties and their evaluated values, items such as PackageReference and ProjectReference, project evaluation data, target execution detail, and files embedded in the log.

That last point matters more than it sounds. The original .csproj, .props, .targets and App.config files may not be on disk at all — when someone hands you a binlog from CI, they usually are not. Read from inside the log or you are reading nothing.

The fallback, and the discipline

Where the MCP server cannot start — an older SDK, an offline environment — the skill falls back to replaying the binlog into text logs with dotnet msbuild build.binlog -noconlog and a set of file loggers that split errors, warnings and a diagnostic-verbosity full log into separate files, then searching those. It includes the PowerShell quoting variant, which is the kind of detail that otherwise costs ten minutes.

It also builds in a stopping rule: synthesise findings as you go and present conclusions once the evidence is sufficient, rather than investigating until the context window runs out. A partial answer with clear reasoning beats a timeout.

Scope

For diagnosing failures from an existing binlog. Generating one is a different skill (binlog-generation, dotnet build /bl:build.binlog), and non-MSBuild build systems are out of scope entirely.

Part of the dotnet-msbuild plugin in the .NET team's official agent skills repository, MIT licensed.

Install

Related Skills

Skill: EF Core Query Optimization

by .NET Team at Microsoft

Make slow Entity Framework Core queries fast — read the generated SQL first, fix N+1s, cartesian Include explosions and non-sargable predicates, then re-measure one change at a time.

Development

Skill: SageMaker HyperPod Cluster Debugger

by AWS Labs

Read-only diagnostics for cluster-wide SageMaker HyperPod failures on EKS or Slurm — CloudFormation errors, EFA health checks, lifecycle scripts, capacity, dangling nodes and autoscaler conflicts.

Development

Skill: Inngest Durable Functions

by Inngest

Featured

Inngest's durable-execution playbook as an agent skill — steps and memoisation, event and cron triggers, idempotency, cancellation, retries and non-retriable errors.

Development

Skill: Inngest v3 to v4 Migration

by Inngest

A controlled upgrade path from Inngest SDK v3 to v4 — triggers into createFunction options, EventSchemas to eventType, realtime imports, step.invoke string IDs — with a scan-first, verify-last order.

Development
Browse all skills →