Because XNNPACK generates a large number of platform-specific source files at build time and depends on a handful of third-party components, its failure modes are fairly consistent across projects. Here's how to work through them in order.
1. Configure step fails immediately
If CMake errors out before it even starts generating build files, check the CMake version first — XNNPACK requires a relatively recent release. Next, confirm the source tree is complete: a missing third_party submodule is the single most common cause of an early configure failure, since several dependencies (like a low-level math library) live there rather than in the main tree.
2. Compile errors partway through
If configure succeeds but compilation stops midway with an error in an unfamiliar-looking generated file, it's almost always related to the compiler version or a missing compiler flag rather than a bug in the library itself. Confirm your compiler supports the C++ standard XNNPACK expects, and that you're not mixing an old compiler with a fresh checkout of the source.
3. Linker errors when building
Undefined reference or unresolved external symbol errors at the link stage usually point to a missing third-party dependency that didn't get built, or a mismatch between a static and shared build configuration somewhere in the dependency chain. Doing a clean rebuild from an empty build directory resolves this more often than you'd expect, since stale CMake cache files can reference paths that no longer match your current setup.
4. Build succeeds, but the library crashes at runtime
An "illegal instruction" crash almost always means a micro-kernel compiled for an instruction set your CPU doesn't support got selected — for example, an AVX512 kernel running on a CPU that only has AVX2. Rebuilding with runtime CPU-feature detection enabled, or restricting the build to a narrower instruction-set target, fixes this.
5. Build works locally, but not in CI
CI runners often use different CPU generations, or run builds in Docker containers with a stripped-down toolchain. Pin the exact compiler and CMake versions in your CI configuration to match what you tested locally, and make sure the CI image includes Python, since XNNPACK's kernel code generation step depends on it.
Still stuck?
If none of the above matches your error, re-check the platform-specific guide for your operating system — our Windows guide and Linux guide both cover platform-specific pitfalls that generic troubleshooting won't catch.