{"record":{"id":"013d186d7ca6a8f7","repo":"cilium/cilium","slug":"failed-to-compile-template-program-w","errorCode":null,"errorMessage":"failed to compile template program: %w","messagePattern":"failed to compile template program: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/datapath/loader/cache.go","lineNumber":157,"sourceCode":"\tif err := os.MkdirAll(dir.Output, defaults.StateDirRights); err != nil {\n\t\treturn \"\", fmt.Errorf(\"failed to create template directory: %w\", err)\n\t}\n\n\theaderPath := filepath.Join(dir.State, common.CHeaderFileName)\n\tf, err := os.Create(headerPath)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"failed to open template header for writing: %w\", err)\n\t}\n\tdefer f.Close()\n\tif err = o.Writer.WriteEndpointConfig(f, cfg); err != nil {\n\t\treturn \"\", fmt.Errorf(\"failed to write template header: %w\", err)\n\t}\n\n\tstats.BpfCompilation.Start()\n\terr = compileDatapath(ctx, o.logger, dir, isHost)\n\tstats.BpfCompilation.End(err == nil)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"failed to compile template program: %w\", err)\n\t}\n\n\to.logger.Info(\n\t\t\"Compiled new BPF template\",\n\t\tlogfields.Path, objectPath,\n\t\tlogfields.BPFCompilationTime, stats.BpfCompilation.Total(),\n\t)\n\n\treturn objectPath, nil\n}\n\n// fetchOrCompile attempts to fetch the path to the datapath object\n// corresponding to the provided endpoint configuration, or if this\n// configuration is not yet compiled, compiles it. It will block if multiple\n// threads attempt to concurrently fetchOrCompile a template binary for the\n// same set of EndpointConfiguration.\n//\n// Returns a copy of the compiled and parsed ELF and a hash identifying a cached entry.","sourceCodeStart":139,"sourceCodeEnd":175,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/pkg/datapath/loader/cache.go#L139-L175","documentation":"After generating the header, build() invokes compileDatapath to run the clang/LLVM toolchain over the template. Any failure there is wrapped as 'failed to compile template program'. The wrapped error typically includes the compiler's stderr via compileDatapath.","triggerScenarios":"compileDatapath returning non-nil: clang not found or wrong version, kernel headers mismatch, compilation error in generated C, context cancelled during compile, or output object not produced.","commonSituations":"Missing clang >= required version in the container image; kernel BPF feature detection mismatch (CONFIG_* options); custom BPF source mount issues; context timeout killing the compile ('signal: killed').","solutions":["Read compiler stderr in the wrapped error for the exact C compile failure","Verify clang/llvm versions installed (clang -version) match requirements","Check kernel BPF config (CONFIG_BPF, CONFIG_BPF_SYSCALL, cgroup/vlan features)","Increase context timeout if compilation was cancelled, and recompile"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Pre-flight: clang present and new enough\nout, err := exec.Command(\"clang\", \"--version\").Output()\nif err != nil {\n    return fmt.Errorf(\"clang not installed: %w\", err)\n}\nif !minLLVMVersion(string(out)) {\n    return errors.New(\"clang too old for BPF compilation\")\n}","typeGuard":null,"tryCatchPattern":"if err := compileDatapath(ctx, logger, dir, isHost); err != nil {\n    if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) {\n        return retryWithLongerTimeout(ctx)\n    }\n    log.Errorf(\"compile failed: %v (stderr in error chain)\", err)\n    return err\n}","preventionTips":["Pin the required clang/LLVM version in images","Compile with a generous context timeout","Check kernel BPF config options before rollout","Capture and persist compiler stderr for debugging"],"tags":["clang","compile","bpf","toolchain"],"backgroundTag":"bpf-compile-failed","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}