cilium/cilium · error

instrumenting %s: %w

Error message

instrumenting %s: %w

What it means

After both hook lists sort successfully, instrumentCollection calls hs.instrumentProgram on the target program's spec to generate the patched instructions; any failure is wrapped as "instrumenting <hookTarget>". This covers BTF metadata extraction, prologue/epilogue generation, and assembling hook calls for that target. Failures here are aggregated via errors.Join and abort Load.

Source

Thrown at pkg/datapath/loader/plugins.go:698

	hooks := make(map[string]*datapathplugins.InstrumentCollectionRequest)
	programPatches := make(map[string]func(asm.Instructions) (asm.Instructions, error))

	for hookTarget, hookTypes := range hs.hooks {
		pre, sortErr := hookTypes[datapathplugins.HookType_PRE].sort()
		if sortErr != nil {
			err = errors.Join(err, fmt.Errorf("%s/%s: %w", hookTarget, datapathplugins.HookType_PRE, sortErr))

			continue
		}
		post, sortErr := hookTypes[datapathplugins.HookType_POST].sort()
		if sortErr != nil {
			err = errors.Join(err, fmt.Errorf("%s/%s: %w", hookTarget, datapathplugins.HookType_POST, sortErr))

			continue
		}
		patch, patchErr := hs.instrumentProgram(cs.Programs[hookTarget], pre, post, hooks)
		if patchErr != nil {
			err = errors.Join(err, fmt.Errorf("instrumenting %s: %w", hookTarget, patchErr))

			continue
		}
		programPatches[hookTarget] = patch
	}

	return hooks, programPatches, err
}

// instrumentProgram generates a program patcher that prepends a dispatcher that
// invokes pre-program hooks, then invokes the original program, and finally
// invokes post-program hooks. Something like this:
//
//	int dispatch(void *ctx) {
//	    int orig_ret, ret;
//
//	    ret = __pre_hook_plugin_a__(ctx);
//	    if (ret != RET_PROCEED)

View on GitHub (pinned to ac7b90affa)

Solutions

1. Check the wrapped inner error from instrumentProgram — most often 'unable to extract function BTF info for target program'.
2. Ensure the target ELF was built with BTF (compile with -g, do not strip .BTF section).
3. Verify the hook target name matches a program present in the loaded collection spec.
4. Confirm the target program type is supported for freplace instrumentation.
5. Exclude the hook/plugin for that target if instrumentation isn't supported there.

Example fix

// before
patch, patchErr := hs.instrumentProgram(cs.Programs[hookTarget], pre, post, hooks)
// after: guard against missing target
prog := cs.Programs[hookTarget]
if prog == nil {
    return nil, fmt.Errorf("hook target %s not found in collection", hookTarget)
}
patch, patchErr := hs.instrumentProgram(prog, pre, post, hooks)

// pre-flight: target exists and has BTF func metadata
prog, ok := cs.Programs[hookTarget]
if !ok || prog == nil {
    return fmt.Errorf("hook target %q missing from collection", hookTarget)
}
if btf.FuncMetadata(&prog.Instructions[0]) == nil {
    return fmt.Errorf("target %q lacks BTF func metadata; rebuild ELF with -g", hookTarget)
}

func instrumentable(spec *ebpf.ProgramSpec) bool {
    if spec == nil || len(spec.Instructions) == 0 { return false }
    meta := btf.FuncMetadata(&spec.Instructions[0])
    if meta == nil { return false }
    _, ok := meta.Type.(*btf.FuncProto)
    return ok
}

if err := load(); err != nil {
    if strings.Contains(err.Error(), "instrumenting ") {
        target := extractTarget(err) // parse wrapped message
        disableHookFor(target)
        return load()
    }
    return err
}

When it happens

Trigger: instrumentProgram fails when the target program lacks function BTF metadata (see 2519), the instructions cannot be rewritten for the requested pre/post hooks, the hook count/context layout mismatches, or the target program is nil/not found in the collection.

Common situations: Kernel/clang compiled the target without BTF (no -g / BTF stripped), so FuncMetadata fails; hook attached to a program type that instrumentation doesn't support; plugin requests hooks on a program that was not loaded (name mismatch).

Related errors

• unable to extract function BTF info for target program
• Unable to determine if BPF_FIB_LOOKUP_SRC is supported
• cannot parse BTF debug info %s: %w
• cannot extract struct info from BTF %s: %w
• looking up type %s by name: %w

AI-assisted analysis of cilium/cilium@ac7b90affa (2026-08-31). Data as JSON: /api/errors/786ee57081638dc2. Report an issue: GitHub.