Fixing Haiku Boot Failures with Safe Mode
Use Haiku Boot Loader Options as controlled tests for video, add-ons, packages, CPUs, interrupts, storage, and logs without blind changes.
Haiku’s Boot Loader Options can isolate a driver, add-on, package state, CPU/interrupt path, or display mode before the normal system starts. Change one option at a time and record the result. Enabling every safe option may produce a bootable system but removes the evidence needed to identify the failing layer.
Enter the correct boot menu
On classic BIOS systems, hold Shift before Haiku begins loading. On UEFI systems, the official user guide says to use Space. If a boot manager is present, start holding the key before invoking its Haiku entry.
Confirm the intended boot volume/state first. On multi-disk systems, a valid but older installation can make the results confusing. Record the Haiku revision shown by the selected state and any recent package or hardware change.
If the Haiku menu never appears, safe-mode switches are not yet the right layer. Check firmware mode, EFI/legacy boot entry, media integrity, partition selection, and installation. The menu appearing proves the firmware reached Haiku’s loader.
Match the first test to the symptom
For a black screen, corrupted display, or hang when graphics should start, enable only fail-safe video. If boot completes, preserve the hardware/graphics identifiers and current resolution. The result implicates the native graphics path; it does not prove the rest of the kernel was failing.
For a regression immediately after installing software, first choose the package state from before the change. Haiku’s package system retains historical states and the loader can boot them. If that works, compare package transactions and remove/update the offending package from a working state.
For software installed under the user configuration hierarchy, test Disable user add-ons. This suppresses user-installed drivers, translators, and other add-ons while retaining the system set. Re-enable/remove candidates one at a time after boot.
Use hardware safe options narrowly
Storage-related stalls may justify the documented IDE DMA compatibility option on applicable legacy controllers. CPU or interrupt hangs can be compared with one-core, APIC/IO-APIC, ACPI, or related options shown by the loader. The exact menu varies by platform/build; read its description rather than copying an unrelated machine’s combination.
A successful conservative mode is diagnostic, not proof hardware is physically broken. Record the exact one switch that changes behavior, controller/CPU model, firmware version, and last debug message. Restore normal settings after updating or removing the responsible component.
Avoid persistent kernel setting edits until the temporary loader test is reproducible. A permanent fail-safe setting can hide improvements in a later update and impose performance/function limits indefinitely.
Collect textual boot evidence
Under debug options, enable on-screen debug output or serial syslog as appropriate. Disable paging only when needed to capture continuous output. Photograph or record the first panic and stack, not only the final repeated line.
The loader can preserve previous-session syslog under supported crash/reboot conditions. Save it after recovery. Include the last boot icon only as supporting context; Haiku’s textual errors identify modules and status codes more precisely.
If Kernel Debugging Land appears, record the panic, current thread, stack trace, loaded module context, and commands/results before rebooting. Do not experiment with KDL memory writes unless developing the kernel.
Repeat the failing boot once with exactly the same options before drawing conclusions. An intermittent device timeout can appear fixed by an unrelated menu change. Record cold versus warm boot and whether removing external USB hardware changes the result.
Recover and fix the actual cause
Once a safe configuration boots, back up important data. Inspect /var/log/syslog, package history, hardware IDs, and user add-ons. For a packaged system component, use the loader’s Disable components feature or Haiku’s documented package blocking mechanism rather than trying to delete a read-only packagefs entry.
Update through the configured repositories, or remove the specific third-party package/driver. Then boot normally twice. If the defect remains, file a report with failing and successful boot settings, revision/architecture, exact hardware, logs, and reproduction sequence.
If no safe option or older state reaches userland, test the same image on known hardware or a current live image, check the storage device and installation media, and preserve kernel output. Reinstalling before saving logs destroys evidence and may stress a failing drive.
The menu is valuable because each switch forms a hypothesis: display driver, user add-on, package transition, storage DMA, interrupt routing, power management, or CPU topology. A controlled difference produces a useful diagnosis; an “everything safe” boot is only emergency access.
Related:
- Haiku’s Boot Process: From Boot Loader to Desktop
- Fixing Display and Graphics Driver Issues in Haiku
Sources: