Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français

The eBPF verifier: why your program is rejected

By updated

Improve this page

The verifier is the piece that makes eBPF acceptable: before any loading, it proves that a program can neither freeze nor corrupt the kernel. It is also what puzzles people most at first, because it rejects programs that look correct. This page explains what it really checks, illustrates two classic rules (the infinite loop and the null map value) with a real rejection captured on a machine, and teaches you to read its messages to understand a rejection. Audience: anyone who deploys eBPF tools or writes them, and runs into a "program rejected". Outputs come from an Ubuntu 24.04 VM (kernel 6.8).

What you will learn

  • Understand what the verifier tries to guarantee, and when it acts
  • Recognize its four major families of rules
  • Decipher a verification log: registers, instruction numbers, faulty line
  • Fix the most frequent rejections (loop, memory access, map value)
  • Observe that a rejection never means a crash: the machine stays intact

What is the verifier for?

An eBPF program runs in the kernel, at the heart of the system. A mistake there does not crash an application, it crashes the whole machine. The verifier is the answer to this risk: a kernel component that analyzes the program before accepting it and rejects it if it cannot prove that it is safe. As long as it has not given the green light, nothing is loaded.

It is a turning point in the history of Linux: it allows anyone, with the right privileges, to have their code run by the kernel without jeopardizing its stability. No other approach (kernel module, patch) offered this guarantee. The price to pay: the verifier is strict, and learning to work with it is part of the job.

How does the verifier work?

The verifier does not test the program by running it. It performs a static analysis: it simulates all the possible execution paths, tracking the state of each register (the memory cells of the eBPF virtual processor) instruction by instruction. For each path, it checks that no rule is violated.

This exhaustiveness has a practical limit: exploring all paths can be costly. The kernel therefore bounds its own work to one million analyzed instructions. Beyond that, it gives up and rejects: this is the guarantee that the verification itself terminates. This bound is visible in every log, in the form limit 1000000.

What are the four major rules of the verifier?

Almost all rejections fall into four families. Each follows from a safety guarantee, documented in the kernel verifier reference.

Rule 1: the program must terminate

A program that never gives control back would freeze the kernel. The verifier therefore demands to be able to prove termination. Historically, every loop was forbidden; the documentation still describes this first pass as a "DAG check to disallow loops" (a check that forbids cycles in the program graph). Since kernel 5.3, it accepts bounded loops, those it can prove stop; it still rejects those it cannot bound.

A loop with no exit condition is therefore rejected. Real captured rejection (program endless_loop, a for (;;) loop):

0: (85) call bpf_ktime_get_ns#5
1: (05) goto pc-2
...
infinite loop detected at insn 1
processed 10 insns (limit 1000000)
Failed to load BPF program 'endless_loop': Invalid argument

The message is explicit: infinite loop detected (insn is short for instruction, and processed 10 insns counts the instructions analyzed). The goto pc-2 instruction is the backward jump that the verifier refuses to let through. Fix: bound the loop (a counter with a constant limit) or, better, use the bpf_loop() helper (kernel 5.17) designed to iterate a known number of times.

Rule 2: memory accesses target the right pointer type

The verifier tracks the type of each register. A memory access (read or write) is allowed only if the register points to a legitimate area. The documentation states it in black and white: "load/store instructions are allowed only with registers of valid types, which are PTR_TO_CTX, PTR_TO_MAP, PTR_TO_STACK". In plain terms, you can only read or write in the event context, a map or the stack of the program, never at an arbitrary address.

Moreover, the access must stay within the bounds of the area. For the stack, the documentation specifies that the address must be "within stack bounds, which are [-MAX_BPF_STACK, 0)". Any attempt to overflow is rejected. This is what prevents a program from reading kernel memory at random.

Rule 3: you do not read uninitialized memory

Reading a stack area that has not been filled first would amount to picking up leftovers from other kernel code, hence to leaking information. The verifier forbids it: "The verifier will allow eBPF program to read data from stack only after it wrote into it". Concretely, an uninitialized buffer, passed to a function that reads it, causes a rejection of the type invalid indirect read from stack. Fix: explicitly initialize the memory, for example with __builtin_memset(&buf, 0, sizeof(buf)).

Rule 4: a map value must be tested against NULL

This is a rejection that most beginners meet. Looking up a key in a map (the shared data structures of eBPF) returns a pointer that may be null if the key does not exist. The verifier marks this pointer with a special type, map_value_or_null, and forbids using it until it has been compared to NULL. The documentation: the type "PTR_TO_MAP_VALUE_OR_NULL becomes a PTR_TO_MAP_VALUE when checked != NULL".

Here is the faulty program, which dereferences the result without testing it:

__u64 *value = bpf_map_lookup_elem(&counter, &key); // may return NULL
*value += 1; // no NULL check

Real rejection, captured on loading with bpftool prog load:

6: (85) call bpf_map_lookup_elem#1 ; R0_w=map_value_or_null(id=1,map=counter,ks=4,vs=8)
; *value += 1;
7: (79) r1 = *(u64 *)(r0 +0)
R0 invalid mem access 'map_value_or_null'
processed 7 insns (limit 1000000)

The fix fits in one line, the missing test:

__u64 *value = bpf_map_lookup_elem(&counter, &key);
if (!value)
return 0;
*value += 1; // here, value is necessarily non-null

With this test, the same program (loaded here under the name deref_checked) loads without a hitch:

194: kprobe name deref_checked tag 8822343a8f08a4f3 gpl
xlated 120B jited 77B memlock 4096B map_ids 8

How do you read a verification log?

The messages look hostile, but they follow a simple logic. Let us go back to the rejection of rule 4, line by line.

  • 6: (85) call bpf_map_lookup_elem#1: instruction number 6 calls the map lookup function. The number in parentheses is the operation code.
  • R0_w=map_value_or_null(...): after the call, register R0 (which holds the return value) is marked "map value or null". The verifier already knows it may be null.
  • 7: (79) r1 = *(u64 *)(r0 +0): instruction 7 reads the memory pointed to by R0. This is the faulty dereference.
  • R0 invalid mem access 'map_value_or_null': the verdict. A read went through a potentially null pointer.

The reflex to debug: spot the last instruction cited (here 7), link it to the matching line of code (the verifier gives it as a comment, ; *value += 1;), and understand which register type was the problem. Most of the time, the fix follows directly from the type mentioned.

Why is a strict verifier a feature?

It is tempting to see the verifier as an obstacle. It is the opposite: its severity is the reason why eBPF can be trusted in production, including on critical machines. An accepted program is a program that the kernel has proven does not loop, does not overflow, does not read forbidden memory. No unit test gives this guarantee.

The counterpart is that you sometimes have to write the code in a way that helps the verifier reason: constant bounds, explicit initializations, systematic null tests. These are not arbitrary contortions, they are the conditions of genuinely safe code.

Troubleshooting

This table maps a verifier message to its meaning and to the gesture that fixes it. It serves as a reference when a loading fails.

Verifier messageWhat it meansFix
infinite loop detected / back-edgeUnbounded loopCounter with a constant limit, or bpf_loop()
invalid mem access 'map_value_or_null'Map value used without a NULL testAdd if (!ptr) return 0;
invalid indirect read from stackRead of an uninitialized stack__builtin_memset before use
R1 type=... expected=...Wrong pointer type for the accessGo through the context, a map or the stack
math between ... pointerUnbounded pointer arithmeticBound the index, mask with & (size - 1)
BPF program is too largeMore than one million instructions analyzedSimplify, split, reduce loop unrolling

Key takeaways

  • The verifier proves, before any loading, that a program can neither freeze nor corrupt the kernel.
  • It performs a static analysis of all paths, bounded to one million instructions.
  • Four major rules: provable termination, memory accesses with the right register types and within bounds, initialized stack before reading, map value tested against NULL.
  • Its messages are readable: spot the last instruction cited and the register type at fault.
  • A rejection is never a crash: nothing is loaded, the machine stays intact.
  • Its severity is a feature: it is what makes eBPF safe in production. You do not try to get around it.

Knowledge check

Check that the essentials of this lesson are in place. The questions only cover what has just been explained here.

Knowledge check

Check what you have learned with this interactive quiz

6 questions
6 min
70% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer