FreeBSD 14 – pkg database locked by stale process – 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

pkg exits with database locked messages, blocking installs and upgrades on production hosts.

Environment & Reproduction

Common after interrupted upgrades or concurrent automation runs.

pkg install -y ca_root_nss
pkg upgrade -y
ps aux | grep pkg

Root Cause Analysis

A previous pkg transaction left lock artifacts or an active process still holds sqlite handles.

Quick Triage

Confirm whether a real pkg process is active before force cleanup.

pgrep -laf pkg
fstat | grep pkg
ls -la /var/db/pkg

Step-by-Step Diagnosis

Identify lock owner and inspect pkg db integrity.

pkg -d update
sqlite3 /var/db/pkg/local.sqlite "PRAGMA integrity_check;"
stat /var/db/pkg/local.sqlite

Solution – Primary Fix

Stop stale processes, remove lock artifacts safely, and repair package database.

pkill -f '^pkg' || true
rm -f /var/db/pkg/.pkg.lock
pkg check -da
pkg update -f

Solution – Alternative Approaches

Rebuild damaged database from package manifests or restore from backup on heavily corrupted systems.

Verification & Acceptance Criteria

pkg operations run without lock errors under normal and automated workflows.

pkg install -y jq
pkg upgrade -n
pkg info | head

Rollback Plan

Revert database and lock cleanup changes if package metadata becomes inconsistent.

service cron stop
cp -a /var/db/pkg /var/db/pkg.rollback
service cron start

Prevention & Hardening

Serialize package jobs, add lock timeout guards, and alert on long-running pkg transactions.

Related Errors & Cross-Refs

Often appears with partial upgrade states and repository fetch interruptions.

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(8), sqlite integrity guidance, and FreeBSD package management best practices.