Your Yocto build failed. The terminal is filled with error messages. You search online and find answers for Kirkstone or Dunfell — but nothing for Scarthgap.
This guide covers the most common Yocto build errors organized by task type, based on Scarthgap 5.0 LTS (BitBake 2.8). Start with the debugging tools, then jump to the task that failed.
If you're new to Yocto, start with the getting started guide.
Log Files and Debugging Tools
Before chasing errors, know where to look and what tools to use.
Log File Locations
BitBake generates a log file for each task.
tmp/work/<ARCH>/<RECIPE>/<VERSION>/temp/
├── log.do_fetch ← do_fetch execution log
├── log.do_compile ← do_compile execution log
├── run.do_compile ← the actual script that was executed
└── ...
The log.do_* files are symlinks pointing to the latest execution. When a build fails, start here.
# Example: check curl's do_compile log
cat tmp/work/core2-64-poky-linux/curl/8.7.1/temp/log.do_compile
bitbake-getvar (Variable Inspection)
Shows the final value of a variable and which file set it.
# Check a recipe-specific variable
bitbake-getvar -r curl SRC_URI
# Check a global variable
bitbake-getvar DISTRO_FEATURES
This shows the value after all :append and :prepend operations have been applied. Use it to verify variables are set as expected.
devshell (Development Shell)
Launches an interactive shell with the same environment variables that BitBake uses. Essential for reproducing and fixing compile errors.
bitbake curl -c devshell
Inside devshell, environment variables like CC, CFLAGS, and LDFLAGS are set exactly as BitBake would set them. Run make clean && make to reproduce the problem and test fixes.
bitbake -e (Full Environment Dump)
When you need to see Python functions or the full expansion history that bitbake-getvar doesn't cover.
bitbake -e curl | grep ^SRC_URI=
do_fetch Errors
Source code download failures. Usually network-related.
URL Changed or Removed
ERROR: curl-8.7.1-r0 do_fetch: Fetcher failure for URL: 'https://example.com/old-url/curl-8.7.1.tar.gz'
The upstream host changed its URL structure. Fix the recipe's SRC_URI or configure a source mirror.
# conf/local.conf — source mirror setup
SOURCE_MIRROR_URL = "http://mirror.example.com/sources/"
INHERIT += "own-mirrors"
git:// Protocol Deprecated
GitHub deprecated the git:// protocol in 2021. Older recipes may still use git://github.com/....
ERROR: curl-8.7.1-r0 do_fetch: Fetcher failure: fetch command failed with exit code 128
Use a bbappend to switch to https:// or add the protocol parameter.
# Fix protocol via bbappend
SRC_URI:remove = "git://github.com/example/repo.git;branch=main"
SRC_URI:append = " git://github.com/example/repo.git;protocol=https;branch=main"
Network Connectivity Issues
For builds behind a proxy or firewall.
# conf/local.conf — proxy settings
HTTP_PROXY = "http://proxy.example.com:8080"
HTTPS_PROXY = "http://proxy.example.com:8080"
For temporary network failures, just re-run the build. BitBake resumes from the failed task automatically.
Checksum Mismatch
ERROR: curl-8.7.1-r0 do_fetch: Checksum mismatch!
The upstream tarball was replaced. The error message shows the correct checksum — update SRC_URI[sha256sum] in the recipe. But first verify the change is legitimate, not a supply chain attack.
do_patch Errors
Patch application failures. Most common when upgrading recipe versions.
Patch Fails to Apply
ERROR: curl-8.7.1-r0 do_patch: Command Error: 'quilt push' failed
Hunk #1 FAILED at 42.
The upstream code changed and the patch context no longer matches.
How to fix:
- Use devshell to investigate
bitbake curl -c devshell
# Inside devshell
quilt push # see which patch fails
quilt push -f # force-apply and check reject files
- Examine the
*.rejfiles to see what couldn't be applied - Manually fix the patch and place it in the recipe's file directory
Patch Order Issues
When SRC_URI lists multiple patches, they're applied in order. If patches depend on each other, the order matters.
SRC_URI = "... \
file://0001-first-fix.patch \
file://0002-depends-on-first.patch"
do_compile Errors
Compilation failures. Causes vary widely.
Parallel Build Races
Intermittent compile errors are often parallel build race conditions.
fatal error: some_header.h: No such file or directory
A source file tries to include a header that hasn't been generated yet because another make job is still building it.
# Diagnose: set PARALLEL_MAKE to 1 for the problematic recipe
PARALLEL_MAKE:pn-problematic-recipe = "-j1"
If -j1 succeeds, it's a parallel race. The proper fix is adding the missing dependency to the recipe's Makefile.
OOM (Out of Memory)
error: internal compiler error: Killed (program cc1plus)
Killed is the OOM killer's signature. Confirm with dmesg.
dmesg | grep -i "oom\|killed"
The fix is reducing parallelism. See the build speed optimization guide for BB_NUMBER_THREADS tuning details.
# conf/local.conf — reduce parallelism
BB_NUMBER_THREADS = "4"
PARALLEL_MAKE = "-j4"
Host Header Conflicts
/usr/local/include/iconv.h:... error: ...
Headers in the host machine's /usr/local/include/ interfere with cross-compilation. This is documented in the official Yocto FAQ.
Fix by renaming the conflicting host headers or using a clean build environment.
do_package_qa Errors
QA (Quality Assurance) check failures. The build itself succeeded, but the package has integrity issues.
installed-vs-shipped
ERROR: QA Issue: <package>: Files/directories were installed but not shipped in any package
Files were installed by do_install but aren't included in any FILES:${PN} variable.
# Fix: add the path to FILES
FILES:${PN} += "${datadir}/myapp"
already-stripped
WARNING: QA Issue: File '/usr/bin/myapp' from myapp was already stripped
The binary was stripped during the build. Yocto strips automatically, so recipe-side stripping is redundant.
# Fix: disable stripping in the recipe
INHIBIT_PACKAGE_STRIP = "1"
ldflags
ERROR: QA Issue: No GNU_HASH in the ELF binary
The linker didn't use the correct LDFLAGS. The build system is ignoring ${LDFLAGS}.
# Fix: pass LDFLAGS to make
EXTRA_OEMAKE += "LDFLAGS='${LDFLAGS}'"
Temporarily Disabling QA Checks
You can suppress specific QA checks while investigating the root cause.
# Suppress QA warnings for a specific recipe (temporary measure)
INSANE_SKIP:${PN} += "already-stripped ldflags"
Other Common Errors
Errors outside of task execution — environment and layer configuration issues.
Cannot Connect to BitBake Server
ERROR: Unable to connect to bitbake server, or start one
A previous BitBake process exited abnormally and left a lock file behind.
# Remove the lock file
rm -f build/bitbake.lock
If that doesn't help, check for other BitBake processes.
ps aux | grep bitbake
LAYERSERIES_COMPAT Mismatch
ERROR: Layer 'meta-custom' is not compatible with the current set of layers
The layer's conf/layer.conf doesn't include scarthgap in LAYERSERIES_COMPAT.
# meta-custom/conf/layer.conf
LAYERSERIES_COMPAT_meta-custom = "scarthgap"
For your own layers, add the line above. For third-party layers, look for a Scarthgap-compatible version or fork and fix. If you're hitting this during a Kirkstone migration, see the migration checklist for the full list of changes.
Nothing RPROVIDES
ERROR: Nothing RPROVIDES 'python3-requests'
The required package isn't provided by any recipe. Two main causes.
- Layer not registered in
bblayers.conf
# Check registered layers
bitbake-layers show-layers
# Add a layer
bitbake-layers add-layer ../meta-python
- Package name mismatch
Yocto package names can differ from distribution names.
# Search for a package
oe-pkgdata-util find-path /usr/bin/python3
Disk Space Exhaustion
No space left on device
A full core-image-sato build requires about 90 GB. Enabling rm_work reduces this to roughly 22 GB. See the build speed optimization guide for details.
# conf/local.conf
INHERIT += "rm_work"
RM_WORK_EXCLUDE += "my-custom-recipe"
Wrapping Up
Yocto build errors can be narrowed down by task type.
| Task | Common Causes | First Check |
|---|---|---|
| do_fetch | URL changes, network, checksums | Error message URL, mirror config |
| do_patch | Context mismatch | devshell with quilt push |
| do_compile | Parallel races, OOM | Retry with -j1, check dmesg for OOM |
| do_package_qa | FILES not set, LDFLAGS | QA error message check name |
The debugging workflow boils down to three steps.
- Read the log:
tmp/work/<ARCH>/<RECIPE>/<VERSION>/temp/log.do_* - Check variables:
bitbake-getvar -r <recipe> <variable> - Reproduce the environment:
bitbake <recipe> -c devshell
Master these three, and you can resolve most build errors on your own.
Understanding the build system internals makes error diagnosis much faster. These books cover Yocto's architecture in depth.