Yocto Fetcher Checksums: Diagnose Named Inputs and Cached Downloads

A checksum error in a Yocto build identifies a failed comparison, but the recipe can contain several downloads and the failing bytes can already be cached. Before changing a digest, connect four things: the source entry, its checksum flag, its local download filename, and the validation path that produced the error.

This diagnostic uses BitBake 2.8 documentation and its upstream maintenance-branch fetcher implementation. It focuses on archive inputs in embedded Linux development with Yocto Project; repository revision selection is a separate mechanism.

Map every named input to its own checksum

The fetch manual allows each source URL to carry a name. Consider an illustrative recipe with a program archive and test-data archive. The first URL ends with ;name=program, and the second ends with ;name=fixtures.

Their expected values belong in SRC_URI[program.sha256sum] and SRC_URI[fixtures.sha256sum]. The value of each flag must be the verified digest for that input, not a digest copied from the other download. These are metadata names, not filenames and not output package names.

Inspect the expanded SRC_URI and those flags in bitbake -e sensor-demo, replacing the recipe name for the actual case. Read the error's local filename and expected value alongside the corresponding entry. If only the fixtures archive changed, editing the program checksum cannot repair that association.

A misspelled name can instead leave an input without an expected digest. That is a missing-checksum problem, even if another flag elsewhere in the recipe contains a perfectly valid SHA-256 value. Resolve the name association before investigating upstream changes.

Different URLs can select the same cache filename

The HTTP fetcher code selects downloadfilename when supplied; otherwise it normally uses the URL path's basename. Two archives from different hosts can therefore both become release.tar.gz in a shared download directory. Giving their URLs different names does not automatically give their cached files different names.

For that case, assign explicit, distinct download filenames, such as sensor-program-1.4.tar.gz and sensor-fixtures-1.4.tar.gz. Keep the names stable for the intended inputs and check other recipes sharing DL_DIR. Diagnose repeated replacement of one cache file before assuming that the upstream release itself is changing repeatedly.

The download search also includes premirrors, the original location, and fallback mirrors. Inspect the fetch log for the endpoint actually tried; do not infer it from the recipe URL alone. If no transfer occurred, the relevant input may be the existing local file. A successful browser download from upstream does not explain what an earlier premirror attempt supplied.

A done stamp does not freeze the recipe's expectation

The BitBake checksum implementation contains verify_donestamp and verify_checksum. For checksum-capable archive inputs, a newer done stamp can supply previously computed digests. Those digests are still compared with the current recipe expectations. If the local file is not older than the stamp, the stored digest is not reused through that timestamp condition.

Consequently, changing a recipe's expected digest can expose a mismatch without a fresh network transfer. Conversely, the presence of a done stamp is not evidence that every invocation reread every archive byte. Avoid diagnosing these cases from the filename suffix alone.

The implementation can rename a mismatching cached file and remove its stamp before retrying. Check the log and directory state before manually clearing anything, particularly when other builders share the cache. Do not deserialize a stamp manually merely to investigate it.

Separate missing policy from mismatching bytes

The strict-checksum variable controls missing expected checksums. For the examined HTTP/archive path, BB_STRICT_CHECKSUM = "1" makes their absence an error. A declared digest that disagrees with the file fails independently; turning strict mode off is not a mismatch repair.

Once names, filenames and the actual source path agree, investigate whether the bytes are an error page, an upstream repack, or a source change. Accept a replacement only after that explanation is established. The immediate BitBake fix should follow the diagnosed branch: correct the flag association, separate colliding cache names, repair the source or mirror, or deliberately accept reviewed new bytes.