swa-troubleshooting

Match the error message against known failure signatures such as metadata mismatches, missing assets, or baseline drift. Then trace the producing MSBuild task or target, using a binlog generated with -bl to inspect item metadata and target execution order.

Identify the target that produces the missing data and the target that consumes it using the binlog. Add an explicit DependsOnTargets declaration on the consuming target so producer targets complete first, especially when BeforeTargets triggers targets too early.

Baseline failures occur when legitimate build output changes but the expected baseline JSON files were not regenerated. The error typically states the generated manifest should match the expected baseline, and the fix is regenerating baselines with the swa-baseline-regeneration skill.

Pack targets use MSBuild conditions based on TFM and feature flags to decide nupkg content. If the test asserts files from a different branch than its configuration activates, update the assertions in Microsoft.NET.Sdk.StaticWebAssets.Pack.targets' matching condition.

Group failures by test class and error signature to find shared root causes, then check whether failing tests target the current or an older TFM. Separate baseline failures from assertion failures, and exclude infrastructure issues like timeouts or Helix agent errors.