FreeBSD 15 – pkg database lock prevents package transactions – Fix & Prevention

📖 ~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

All package operations fail with lock errors, interrupting maintenance and deployments.

Environment & Reproduction

Occurs when parallel automation runs pkg simultaneously.

pkg update
pkg upgrade -y
ps aux | grep pkg

Root Cause Analysis

A stale or active lock file blocks concurrent write access to the package database.

Quick Triage

Identify active pkg processes before removing lock artifacts.

fstat | grep /var/db/pkg
ps -ax | grep -E 'pkg|pkg-static'
ls -la /var/db/pkg

Step-by-Step Diagnosis

Validate whether lock holder is active or orphaned after interruption.

procstat -f $(pgrep -f pkg | head -n1) 2>/dev/null || true
lockf -k /var/db/pkg/.pkg.lock true 2>/dev/null || true
tail -n 100 /var/log/messages

Solution – Primary Fix

Terminate stale processes, clear lock, and repair package state.

pkill -f pkg || true
rm -f /var/db/pkg/.pkg.lock
pkg check -da
pkg upgrade -y

Solution – Alternative Approaches

Reboot during a maintenance window to clear process state safely.

shutdown -r +1 "Reboot to clear stale pkg lock"

Verification & Acceptance Criteria

pkg update and installs run normally with no lock contention.

pkg update
pkg install -y jq
pkg check -sa

Rollback Plan

Revert any automation changes that introduced overlapping package operations.

crontab -l
service cron restart

Prevention & Hardening

Serialize package tasks and add lock-aware retry logic in orchestration.

lockf -s -t 0 /var/run/pkg-maint.lock pkg upgrade -y

Related Errors & Cross-Refs

Often appears with interrupted upgrades and filesystem full conditions under /var.

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

pkg-locking behavior and FreeBSD operations best practices.