Diagnosing a Shipping Build Failure in Under Five Minutes

A shipping build fails in CI. The log is 14,000 lines. The first visible error is a linker failure, but the actual root cause is an include order issue three modules upstream. Two engineers have already spent an hour scrolling through the log and are looking at different theories. This is the scenario where Build Doctor earns its keep.

The project is a mid-size Unreal title with 47 modules, targeting Win64 Shipping. The CI pipeline runs a full BuildCookRun step and had been green for three days. A merge from a feature branch introduced a new header dependency that compiled fine in Development configuration but failed in Shipping due to a different include order enforced by Unity builds.

• 14,000+ lines of build output
• Visible symptom: linker error in module GameplayAbilities
• Actual root cause: include order issue in a custom module three dependency levels upstream
• Two engineers had been investigating for over an hour

Build Doctor was pointed at the CI build log. It classified the failure, traced the dependency chain, and returned three ranked findings in structured format.

gamibase doctor --log ci-build-shipping.log --format json

Finding 1: Include order violation

The top-ranked finding identified the actual root cause — a new header in the custom CoreSystems module that assumed a specific include order. Build Doctor traced the dependency chain from the linker error back through two intermediate modules to the source header, identifying the exact file and line where the include assumption broke under Unity build rules.

Finding 2: Missing forward declaration

The second finding identified a related issue — a missing forward declaration that was masked in Development config by a transitive include but became a hard error in Shipping. This was not the root cause of the CI failure, but it would have caused the next one.

Finding 3: Module dependency suggestion

The third finding suggested a .Build.cs dependency that was implicitly satisfied but not explicitly declared — the kind of issue that works until someone restructures the module graph.

The engineer reviewed the three findings, confirmed the include order diagnosis against the source, and pushed a two-line fix. The CI pipeline went green on the next run. Total time from running Build Doctor to a merged fix: under five minutes. The previous hour of manual investigation had been looking at the linker error directly — the wrong layer.

• Build Doctor understood the module dependency graph, not just the error text
• It traced upstream from the visible symptom to the originating header
• It distinguished between the root cause and related-but-secondary issues
• The structured output gave the engineer something to review instead of a log to scroll