FreeBSD 15 – boot fails after invalid loader.conf module settings – 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

System fails to boot fully or drops to loader prompt after kernel module changes.

Environment & Reproduction

Triggered by manual edits to /boot/loader.conf with incorrect module names.

cat /boot/loader.conf
cat /boot/loader.conf.local
kldstat

Root Cause Analysis

Invalid loader directives cause module load failure early in boot sequence.

Quick Triage

Use single-user mode and inspect recent boot and loader changes.

nextboot -D
ls -l /boot/kernel
cat /boot/loader.conf

Step-by-Step Diagnosis

Validate every module directive against available kernel module files.

awk -F= '/_load="YES"/{print $1}' /boot/loader.conf
find /boot/kernel -name '*.ko' | sed 's#.*/##' | sort | head
dmesg | tail -n 80

Solution – Primary Fix

Disable invalid module entries, keep only required modules, and reboot.

cp -a /boot/loader.conf /boot/loader.conf.bak
vi /boot/loader.conf
reboot

Solution – Alternative Approaches

Move optional module loading from loader.conf to rc.conf for safer runtime loading.

sysrc kld_list+="if_bridge"
service kld restart 2>/dev/null || true

Verification & Acceptance Criteria

Boot completes normally and required modules load without errors.

kldstat
dmesg | grep -i -E 'error|failed'
service -e

Rollback Plan

Restore prior loader.conf backup if required devices disappear after cleanup.

cp -a /boot/loader.conf.bak /boot/loader.conf
reboot

Prevention & Hardening

Review module changes with staged reboot testing before production rollout.

cp /boot/loader.conf /boot/loader.conf.$(date +%Y%m%d)

Related Errors & Cross-Refs

Related to kernel ABI mismatch and post-upgrade third-party module incompatibilities.

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 loader.conf, module loading, and boot troubleshooting documentation.