FreeBSD 14 – pkg Database Lock Prevents Install and Upgrade – Safe Unlock Procedure

📖 ~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 operations fail with lock errors, blocking urgent installs and security updates.

Environment & Reproduction

Typically appears when automation runs overlapping pkg transactions.

ps aux | grep -E 'pkg|pkg-static'
ls -lah /var/db/pkg

Root Cause Analysis

Active or stale lock artifacts remain from interrupted package transactions.

Quick Triage

Confirm whether any legitimate pkg process still owns the lock.

fstat -f /var/db/pkg
procstat -a | grep pkg

Step-by-Step Diagnosis

Correlate running processes and lock files to determine stale vs active ownership.

tail -n 120 /var/log/messages
ls -lah /var/db/pkg/.lock

Solution – Primary Fix

Stop conflicting jobs, remove stale lock safely, then rerun package metadata refresh.

pkill -f pkg || true
rm -f /var/db/pkg/.lock
pkg update -f

Solution – Alternative Approaches

Serialize all package operations into one maintenance pipeline to avoid lock races.

Verification & Acceptance Criteria

Test install and info commands complete without lock errors.

pkg install -y ca_root_nss
pkg info | head

Rollback Plan

Restore package DB backup if transaction metadata is inconsistent.

cp -a /var/db/pkg /var/db/pkg.backup.$(date +%F)

Prevention & Hardening

Enforce single-writer package maintenance and monitor failed automation runs.

Related Errors & Cross-Refs

Cannot get an advisory lock on a database, pkg: sqlite error.

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 operations and maintenance best practices.