Ninja "build stopped: subcommand failed" in CI

By Kaveh Alemi·Latchkey

Ninja is only reporting that one of the commands it ran returned a non-zero exit code. The actual compiler or linker error is printed above; "subcommand failed" is the summary, not the cause.

What this error means

The build ends with "ninja: build stopped: subcommand failed." after a compiler or linker error scrolled by earlier in the log.

src/main.cpp:10:5: error: use of undeclared identifier 'foo'
ninja: build stopped: subcommand failed.

Common causes

A compile or link command exited non-zero

Ninja ran a rule (compile, link, custom command) that failed; it aborts and prints the summary.

Parallel output hides the first real error

With many jobs in flight, the failing command's output can be buried above the summary line.

How to fix it

Scroll up to the first error line

1. Find the first error: or fatal error: above the summary.
2. Fix that specific compile or link failure.
3. Re-run the build; the summary clears once the subcommand succeeds.

Reduce parallelism to isolate the failure

Build with a single job so the failing command's output is not interleaved.

cmake --build build -- -j1

How to prevent it

• Treat "subcommand failed" as a pointer to the earlier real error.
• Use -j1 locally when a parallel log is hard to read.
• Keep warnings-as-errors consistent so the first failure is deterministic.

Frequently asked questions

Related guides

References

• CMake documentation
• GitHub Actions documentation