go-delve/delve · error

eBPF map not loaded

Error message

eBPF map not loaded

What it means

EBPFContext.UpdateArgMap writes breakpoint argument type metadata into the eBPF map (bpfArgMap) used by the trace program to serialize argument bytes. If the map was never loaded (program load failed or was skipped) there is nowhere to write the metadata, so this error is returned.

Source

Thrown at pkg/proc/internal/ebpf/helpers.go:199

	}

	if ctx.objs != nil {
		ctx.objs.Close()
	}
}

func (ctx *EBPFContext) AttachUprobe(pid int, name string, offset uint64) error {
	if ctx.executable == nil {
		return errors.New("no eBPF program loaded")
	}
	l, err := ctx.executable.Uprobe(name, ctx.objs.tracePrograms.UprobeDlvTrace, &link.UprobeOptions{PID: pid, Address: offset})
	ctx.links = append(ctx.links, l)
	return err
}

func (ctx *EBPFContext) UpdateArgMap(key uint64, goidOffset int64, args []UProbeArgMap, gAddrOffset uint64, isret bool) error {
	if ctx.bpfArgMap == nil {
		return errors.New("eBPF map not loaded")
	}

	// Store DWARF types and parameter names for later lookup during ring buffer
	// event parsing. Uses a global index: input params at 0..n-1, return params
	// at n..n+m-1. Held under ctx.m to prevent data race with pollEvents.
	ctx.m.Lock()
	if !isret {
		ctx.nInputParams[key] = len(args)
	}
	nInputs := ctx.nInputParams[key]
	for i, arg := range args {
		idx := i
		if isret {
			idx = nInputs + i
		}
		k := dwarfTypeKey{fnAddr: key, paramIdx: idx}
		ctx.paramInfo[k] = paramMeta{dwarfType: arg.DwarfType, name: arg.Name}
	}

View on GitHub (pinned to a23773e6c3)

Solutions

1. Fix eBPF loading first: ensure privileges (sudo/CAP_BPF, CAP_PERFMON) and a supported kernel, then retry the trace session
2. Rebuild the eBPF object for your architecture (make build-ebpf-object) so all maps exist
3. Check dlv startup logs for the original InitializeEBPF failure that left the map unloaded
4. Fall back to regular (non-eBPF) tracepoints with 'dlv trace' without --ebpf

// ensure eBPF context initialized successfully before tracing:
if err := checkEBPFAvailable(); err != nil { // capabilities + kernel + object load
    return err // don't proceed to UpdateArgMap paths
}

if err := ebpfCtx.UpdateArgMap(key, goidOff, args, gAddrOff, isret); err != nil {
    if strings.Contains(err.Error(), "eBPF map not loaded") {
        log.Printf("arg map unavailable, falling back: %v", err)
        useRegularTrace()
    }
}

When it happens

Trigger: Calling UpdateArgMap (invoked when setting an eBPF trace breakpoint) after EBPFContext creation where ctx.bpfArgMap is nil — e.g. the eBPF objects partially loaded but the arg map failed, or a disabled/stub context was used.

Common situations: Same environment problems as program-not-loaded: missing capabilities, kernel too old, seccomp-restricted container; mismatched or stale compiled eBPF object missing the arg map section; using a custom build that skipped map creation.

Related errors

• too many arguments in traced function, max is 12 input+retur
• no eBPF program loaded
• eBPF is disabled
• failed to remove memlock limit (try running with CAP_SYS_RES
• map type not yet supported by ebpf tracing

AI-assisted analysis of go-delve/delve@a23773e6c3 (2026-08-31). Data as JSON: /api/errors/1100a6ba6f2a7c9a. Report an issue: GitHub.