FreeBSD 12 – 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 or signature metadata mismatch errors, delaying security patching.

Environment & Reproduction

Usually appears after mirror rotation, interrupted updates, or stale local package catalogs.

freebsd-version
pkg -vv | head -n 40

Root Cause Analysis

Local repo catalog and remote package metadata differ, so pkg cannot safely resolve package indexes.

Quick Triage

Confirm DNS reachability and force a fresh catalog pull.

drill pkg.freebsd.org
pkg update -f

Step-by-Step Diagnosis

Inspect pkg configuration and cache artifacts for stale catalogs.

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

Solution – Primary Fix

Clear stale package metadata and rebuild the local repository catalog.

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

Solution – Alternative Approaches

Pin to a known-good internal mirror if upstream mirrors are unstable.

pkg -o REPOS_DIR=/usr/local/etc/pkg/repos update -f

Verification & Acceptance Criteria

Repository update and package upgrade complete without checksum or catalog errors.

pkg update
pkg upgrade -n

Rollback Plan

Restore previous repository config files if a mirror override causes package selection drift.

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

Prevention & Hardening

Standardize repository definitions and monitor mirror latency and failures.

pkg stats
tail -n 100 /var/log/messages

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-12.

View all freebsd-12 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

FreeBSD pkg handbook and package repository administration guidance.