Troubleshooting operating system problems can be difficult.
To give us the best assistance resolving bugs within Haiku, please be sure to add details to existing bug reports, or create a new bug report with as much information as possible. More information on reporting bugs can be found here
When Haiku fails to boot on a machine, it generally fails in one of the following ways:
Kernel Debug land
The Kernel Debug Land is the debugger built into Haiku’s kernel and represents a captured critical exception within the operating system.
Non-fatal KDL exceptions can sometimes be worked around by typing
continue into the KDL screen. This rarely works however as KDL exceptions are generally raised with good reason.
If the source of the problem is identified in the KDL, the add-on or driver can be blacklisted using the
Blacklist entries bootloader menu.
KDL exceptions should always be reported to the Haiku bug tracker. (either by searching for existing bugs, or reporting new undiscovered bugs)
Since obtaining the data in a KDL can be challenging at times, the following steps are generally used to report KDL exceptions to the Haiku developers:
btis run to ensure a detailed backtrace is shown on screen.
- A picture is taken of all text on the screen ensuring the text is as clear as possible.
- The picture is provided to existing or new bug reports with the architecture and build (hrevXXXXXX)
Blank or corrupted screen after booting
A black, blank, or corrupted screen after booting can be caused by several different issues and can be a tricky issue to debug.
The easiest approach to resolving a black/blank/corrupted screen at boot is to leverage the
Use fail-safe video mode boot option. This will disable any specialized hardware acceleration or mode setting and fall back to basic VESA or Frame buffer based video resolutions and rendering.
You can configure Haiku to always boot using the fail-safe video driver by enabling 'fail_safe_video_mode' in ~/config/settings/kernel/drivers/kernel
Reporting detailed information from computers experiencing black/blank/corrupted screens can be difficult given their nature. Sometimes the host is responsive, however the end user is unable to determine the state of the machine.
- Serial Debugging is the fastest and most accurate way to obtain debug data from a uncooperative system. This method however requires a built-in serial port and specialized hardware and cables.
- Obtaining system logs is possible in some circumstances.
- Boot the system until the black screen is encountered and wait 30 seconds.
- Hold + + for 5 seconds (or until system reboots)
- Boot the system, leverage the
Use fail-safe video modeboot option.
- Make a copy all files in /var/log/syslog* and provide to Haiku via an existing or new bug report.
Instant reboot represents the worst-case scenario and can be extremely difficult to troubleshoot.
Leveraging various boot options such as
Safe mode may provide relief to these serious issues. Reporting instant reboot issues using the steps below to the Haiku developers is highly encouraged.
Serial Debugging is the only real way to obtain debugging data from instant reboot problems. This method however requires a built-in serial port and specialized hardware and cables.