Troubleshooting

Start with the first line of the error, not the last. BEP prints a stable prefix for every failure, and the table below maps each prefix to one check and one fix.

Updated 2026-10-09Applies to 2.8.1Reading time 7 minutes

Symptoms at a glance

Message starts with	Likely cause	Fix
`error: context mismatch`	Upstream changed under a patch, or the wrong base in the header	`bep apply --3way`, then update `base`
`error: lock is stale`	A patch file changed after the last apply	`bep apply` to rewrite the lock, or restore the patch
`error: cmake configure failed`	Missing tool or a path with spaces	Run `bep doctor`; move the series to a path without spaces
`error: compiler killed`	Out of memory during a parallel compile	Lower `--jobs` to cores − 2
`error: verify mismatch`	Line endings, generated file or an edit outside the series	`bep verify --manifest`, inspect the named file
`error: disk full`	Sources plus output exceed the volume	`bep cache gc`, free 20 GB, retry
`error: patch skipped`	An optional patch no longer applies	Make it mandatory, or drop it from the manifest
`error: dependency cycle`	Two patches require each other	`bep series order --check` prints the cycle

Apply fails after an upstream move

A patch is written against a base revision. When the mirror moves, the same hunk may still be valid two hundred lines away; a three-way apply resolves that without touching your file. Look at what changed before accepting it:

$ bep apply --3way --dry-run
would apply  0200-debug-hooks   3 files
  merged     content/browser/devtools/host_impl.cc  (offset 212, 0 conflicts)
  merged     build/config/compiler/BUILD.gn         (offset 4, 0 conflicts)
2 patches, 0 conflicts

$ bep apply --3way
applied      0200-debug-hooks   3 files (2 merged)
warning      patch base 8f2c41d9 is behind the pinned revision 9a1f0c22

The warning is not an error, but it is a task: update base, run the tests the patch names, and commit. A merged patch that you leave at an old base will collect silent drift.

Verification mismatch on one file

Nine times out of ten this is line endings. A checkout made on Windows and opened in an editor that normalises CRLF produces the same content but a different hash. 2.8.1 reports the file and both hashes:

$ bep verify --manifest
mismatch  content/browser/devtools/host_impl.cc
          expected 3f9a1c...  actual 8b7e04...
          2 917 matched, 1 differs

Run bep apply --from-scratch --patch debug-hooks to rebuild the file from the patch. If the mismatch repeats, the patch lacks a final newline; add one rather than teaching the verifier to ignore it.

Build dies with no compiler error

The kernel's out-of-memory killer leaves no compiler message. Check dmesg | tail for Out of memory: Killed process, then lower the job count. Each job can peak at 2.5 GB; a 16 GB machine with 12 jobs will swap on a large translation unit even when the average looks fine. On a 32 GB machine, 12 jobs is comfortable; on 64 GB, 20 is the practical ceiling because link steps serialise.

Apply succeeds, build ignores the change

Two causes, both common. First, bep build was not run after bep apply; the build system caches configured inputs, and apply prints tree changed, run build when it detects this. Second, the patch writes a file that the target does not compile (a different platform directory, or a generated file that is regenerated). bep apply --dry-run lists the files it would touch; compare that list with the build target.

Patches are skipped

A skipped patch is always one marked optional. It appears in the summary with the reason, never as silence:

$ bep apply
applied      0100-build-flags     6 files
skipped      0200-debug-hooks     optional, context mismatch at line 148
1 patch applied, 1 skipped (exit 0)

If a skipped patch should have applied, set optional = false in the manifest so the next run fails instead of continuing. CI profiles do this by default with series.optional = false; see Configuration.

Collecting a useful report

bep --version
bep doctor --json > doctor.json
bep apply --dry-run --log-level debug 2> apply.log
bep verify --manifest > verify.txt

Attach those four files to the report. They contain paths and hashes, never file contents. The log is plain text and can be reviewed before sending; the community page explains where to send it.

Slow builds

Measure before changing anything. A first build without ccache on 12 cores takes 70 to 90 minutes; an incremental build after a one-file patch takes three to five. If an incremental build takes twenty, check bep build --stats for cache misses: a changed compiler flag in build-flags invalidates every object, and that patch changes flags by design. Remove it from the series to keep a long-lived object cache.