FreeBSD 14 – pkg Repository Metadata Out of Sync Blocks Upgrades – Recovery Steps

📖 ~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

pkg update and pkg upgrade fail with repository metadata mismatch errors, delaying patching windows.

Environment & Reproduction

Common after stale mirror caches or interrupted catalog refresh on FreeBSD 14 hosts.

freebsd-version
pkg -vv | head -n 40

Root Cause Analysis

Local package catalog state diverges from remote repository metadata and checksum indexes.

Quick Triage

Validate DNS and force a catalog refresh before deeper remediation.

drill pkg.freebsd.org
pkg update -f

Step-by-Step Diagnosis

Inspect repository definitions and stale sqlite metadata under /var/db/pkg.

grep -R 'url:' /etc/pkg /usr/local/etc/pkg/repos
ls -lah /var/db/pkg

Solution – Primary Fix

Remove stale repo databases, bootstrap pkg metadata again, and retry upgrades.

rm -f /var/db/pkg/repo-*.sqlite
pkg bootstrap -f
pkg update -f
pkg upgrade -y

Solution – Alternative Approaches

Temporarily pin to a known-good internal mirror while upstream mirrors stabilize.

Verification & Acceptance Criteria

Repository refresh and dry-run upgrade complete with no checksum or catalog errors.

pkg update
pkg upgrade -n

Rollback Plan

Restore previous repo config if a mirror override causes package drift.

cp -a /usr/local/etc/pkg/repos /usr/local/etc/pkg/repos.rollback.$(date +%F)

Prevention & Hardening

Standardize repository definitions and monitor fetch failures from package mirrors.

Related Errors & Cross-Refs

pkg: repository catalog is malformed, signature mismatch, failed to fetch repository meta.

Related tutorial: View the step-by-step tutorial for freebsd-14.

View all freebsd-14 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

FreeBSD pkg handbook and repository operations guidance.