FreeBSD 12 – Common Problem 001 – pkg Repository Metadata Is Stale

📖 ~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` returns repository fetch errors, so security patches and package installs fail.

Environment & Reproduction

On FreeBSD 12 hosts behind strict egress filtering, run `pkg update -f` and observe repeated catalog download failures.

Root Cause Analysis

Common causes are outdated CA bundles, broken DNS, or blocked HTTPS to pkg mirrors.

Quick Triage

Confirm network and repo config before deeper changes.

pkg -vv
cat /usr/local/etc/pkg/repos/FreeBSD.conf
dig pkg.freebsd.org

Step-by-Step Diagnosis

Validate resolver, TLS trust store, and outbound HTTPS from the host.

sockstat -4 -6 | grep -E 'unbound|named'
fetch -vo /tmp/meta.txz https://pkg.freebsd.org/FreeBSD:12:amd64/latest/meta.txz
certctl rehash

Solution – Primary Fix

Repair trust and force catalog refresh.

pkg install -y ca_root_nss
certctl rehash
pkg update -f

Solution – Alternative Approaches

Switch temporarily to a local mirror in `/usr/local/etc/pkg/repos/` if upstream connectivity is constrained.

Verification & Acceptance Criteria

`pkg update` completes without errors and `pkg upgrade -n` lists packages normally.

Rollback Plan

Restore previous repo file from backup and revert mirror changes if packages resolve to unexpected origins.

Prevention & Hardening

Schedule periodic `pkg update -q`, monitor certificate expiry, and allow approved mirror endpoints in firewall policy.

Related Errors & Cross-Refs

`repository FreeBSD has no meta file`, `SSL certificate problem`, `pkg: No SRV record found`.

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 Handbook package management chapter, `pkg.conf(5)`, `certctl(8)`.