FreeBSD 15 – poudriere build fails from distfile checksum mismatch – Fix & Prevention

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

Package build pipeline stops, delaying patched package delivery for internal repos.

Environment & Reproduction

Seen when upstream distfiles change or cache corruption occurs.

poudriere bulk -j 15amd64 -p default editors/vim
tail -n 80 /usr/local/poudriere/data/logs/bulk/*/logs/errors.log

Root Cause Analysis

Downloaded distfile hash no longer matches expected digest in the ports tree.

Quick Triage

Validate ports tree freshness and locate failing distfile artifact.

poudriere ports -l
git -C /usr/ports status
find /usr/ports/distfiles -type f | wc -l

Step-by-Step Diagnosis

Inspect make checksum output and compare cached distfile hashes.

cd /usr/ports/editors/vim && make checksum
sha256 /usr/ports/distfiles/*vim* 2>/dev/null | head
fetch -vo /tmp/test.tar.gz 

Solution – Primary Fix

Purge corrupted distfiles, update ports tree, and rebuild target set.

rm -f /usr/ports/distfiles/
git -C /usr/ports pull --ff-only
poudriere bulk -j 15amd64 -p default editors/vim

Solution – Alternative Approaches

Pin to a quarterly branch while upstream distfile transitions settle.

poudriere ports -u -p quarterly

Verification & Acceptance Criteria

Build completes and repository metadata publishes without checksum errors.

poudriere queue -j 15amd64
poudriere status
ls /usr/local/poudriere/data/packages/15amd64-default

Rollback Plan

Revert ports tree commit and rebuild from previous known-good snapshot.

git -C /usr/ports reset --hard 

Prevention & Hardening

Use mirrored distfile cache and periodic integrity checks.

poudriere distclean -a
cronjob='0 2 * * * git -C /usr/ports pull --ff-only'

Related Errors & Cross-Refs

Related to TLS fetch failures, expired certificates, and mirror poisoning concerns.

Related tutorial: View the step-by-step tutorial for FreeBSD 15.

View all FreeBSD 15 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

poudriere handbook and FreeBSD ports maintenance guidance.