FreeBSD 14 – pkg upgrade blocked by locked dependency chain

📖 ~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 upgrade aborts because required dependencies are locked. Critical fixes cannot be applied and package graph drifts from supported state.

Environment & Reproduction

Typically appears after manual package pinning during emergency changes.

pkg info -k
pkg upgrade -n
pkg lock -l

Root Cause Analysis

A lock on one package prevents solver actions for the dependency tree, creating an unsatisfied upgrade plan.

Quick Triage

Identify minimal set of locks that block security updates.

pkg lock -l
pkg upgrade -n | sed -n '1,200p'
pkg check -da

Step-by-Step Diagnosis

Inspect reverse dependencies and confirm whether lock is still required.

pkg query '%n %ro'
pkg rquery -r FreeBSD '%n %dn' | head -n 50
pkg version -vL=

Solution – Primary Fix

Temporarily unlock only the required chain, perform upgrade, then relock if policy requires.

pkg unlock 
pkg upgrade -y
pkg lock 

Solution – Alternative Approaches

Use per-package targeted upgrade when broad upgrade windows are restricted.

pkg install -f 
pkg upgrade -n
pkg autoremove -n

Verification & Acceptance Criteria

Upgrade plan is clean and no dependency conflicts remain.

pkg upgrade -n
pkg check -d -a
pkg audit -F

Rollback Plan

Re-lock packages and restore previous package set snapshot if application tests fail.

pkg lock 
pkg info > /root/pkg-info.rollback.txt

Prevention & Hardening

Track lock reasons and expiry dates in change records to avoid forgotten constraints.

pkg lock -l
logger -t pkg 'review locked packages monthly'

Related Errors & Cross-Refs

Often linked with stale local ABI assumptions and partial repository sync windows.

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

pkg-lock manual references and FreeBSD package branch policy notes.