Daemon Fails Because Missing Shared Library After pkg Operations

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

Partial package upgrades can remove required ABI-compatible libraries and break service startup.

Environment & Reproduction

Daemon exits with shared object not found and service scripts report immediate failure.

Root Cause Analysis

Hosts with mixed repository branches or interrupted pkg upgrade transactions.

Quick Triage

Root access and ability to reinstall packages from configured repositories.

Step-by-Step Diagnosis

[image_ref: 0] Run service daemon_name onestatus; ldd /usr/local/sbin/daemon_binary; pkg info -d package; pkg check -da.

Solution – Primary Fix

[image_ref: 1] Ensure a single branch policy in repository config and no stale lock files under /var/db/pkg.

Solution – Alternative Approaches

Reinstall missing libraries and affected package with pkg install -f, run pkg upgrade to converge versions, then restart service.

Verification & Acceptance Criteria

ldd shows all dependencies resolved and daemon stays running after restart.

Rollback Plan

Downgrade to previously working package set only if forced compatibility changes break production workloads.

Prevention & Hardening

Avoid mixing quarterly and latest repos and complete upgrades in one maintenance window.

Related Errors & Cross-Refs

Escalate if ABI conflicts involve custom ports or third-party binary repositories.

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), ldd(1), rtld(1), FreeBSD package management best practices.