FreeBSD 15 – 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 stop with lock errors, blocking installs and urgent updates.

Environment & Reproduction

Seen when multiple automation jobs run pkg concurrently.

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

Root Cause Analysis

An active package transaction or stale lock remains from an interrupted pkg process.

Quick Triage

Identify running package jobs before touching lock state.

procstat -a | grep pkg
service cron status

Step-by-Step Diagnosis

Validate whether lock ownership is live or stale from prior failures.

fstat -f /var/db/pkg
tail -n 120 /var/log/messages

Solution – Primary Fix

Stop conflicting pkg tasks, remove stale lock artifacts, and retry safely.

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

Solution – Alternative Approaches

Serialize package jobs through one scheduled maintenance pipeline.

Verification & Acceptance Criteria

A test package operation completes with no lock error.

pkg install -y ca_root_nss
pkg info | head

Rollback Plan

Restore package DB backup if transaction metadata becomes inconsistent.

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

Prevention & Hardening

Enforce single-writer package maintenance and monitor failed pkg 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-15.

View all freebsd-15 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

FreeBSD pkg operational best practices and maintenance workflows.