Fixing Display and Graphics Driver Issues in Haiku
A controlled Haiku graphics workflow using fail-safe video, exact adapter IDs, conservative modes, logs, component blocking, and reports.
A blank screen, corrupted image, wrong mode, or missing second monitor can originate in firmware handoff, native graphics driver, display detection, or one mode-setting path. Use fail-safe video as a comparison, not as proof that every graphics symptom has the same cause.
Compare native and fail-safe graphics
Enter Boot Loader Options—hold Shift on BIOS systems or Space on UEFI—and enable only the fail-safe video option. Keep the same boot volume and package state. If the system reaches the desktop only in this mode, record that difference and the exact point where native boot failed.
Fail-safe output bypasses important parts of the native driver/accelerant path, so success narrows the problem. It does not prove the GPU is defective or that VESA/firmware output supports every resolution, refresh rate, acceleration feature, or multi-monitor configuration.
If fail-safe mode is also blank, enable textual boot output and investigate whether the kernel or app_server reaches graphics at all. Preserve the last messages before changing packages.
Identify adapter, driver, and display
Once booted, save listdev output and relevant /var/log/syslog lines. Record vendor/device IDs, laptop or motherboard model, firmware mode, monitor connection (HDMI/DP/internal panel), Haiku revision/architecture, and graphics package/driver named in logs.
Open Preferences → Screen and note available modes, reported display, color depth, and refresh. Do not assume a marketing GPU family identifies the exact PCI revision. Hybrid graphics laptops may expose more than one adapter while firmware routes the panel through only one.
For a monitor-specific problem, test one display and one direct cable first. Remove docks/adapters, then add the second display after the single-display baseline is recorded. A working primary does not demonstrate complete multi-monitor support.
Test modes conservatively
Choose a mode listed by Screen preferences rather than typing arbitrary timing values. Start with a conservative resolution/refresh supported by the monitor, apply it, and verify redraw, cursor, window movement, video, and reboot persistence.
If one mode fails, record the exact resolution, refresh, connector, and whether the monitor loses signal or the desktop corrupts. Restore the previous mode through fail-safe boot if necessary. Repeatedly applying unstable timings without recording them can leave settings that reproduce the black screen.
Display identification data can also be wrong or incomplete. Compare modes reported with another cable/connector and the monitor’s own information panel. If the native driver offers an impossible mode or omits the panel’s native mode, include that list in the report; it narrows the issue to display detection/EDID or mode validation rather than drawing primitives.
Do not interpret missing acceleration as total driver failure. Framebuffer output, mode setting, 2D acceleration, overlays, and multi-monitor can have separate support. Report the first unsupported operation rather than “graphics do not work.”
Isolate packages and settings
If the regression began after an update, boot the previous package state from the loader with no other changes. A working old state supplies a precise revision range. Do not copy an older accelerant or kernel driver into the current packagefs view; matching userland/kernel components matter.
Back up the Screen preferences settings before resetting them. If a clean setting restores native boot, reapply one mode at a time. If the driver is packaged in the base system and prevents boot, use the loader’s temporary Disable components feature or Haiku’s documented package-blocking mechanism instead of deleting read-only files.
Test a current supported live image/nightly when safe to learn whether the hardware gap is already fixed. Keep installation and live-media results separate because their revisions/settings differ.
File an actionable graphics report
Attach revision/architecture, exact PCI IDs, system/firmware model, connector/monitor, native versus fail-safe result, failing and working modes, syslog, and boot debug output. Include a photo for corruption that screenshots cannot capture; if screenshots capture it, attach both.
State whether the failure occurs before desktop, on mode switch, after sleep, during video, or when attaching a display. Search Haiku’s tracker by vendor/device ID and add evidence to the matching ticket rather than opening a duplicate by product nickname.
Also distinguish corruption captured by Haiku’s Screenshot tool from corruption visible only in a phone photo. A correct screenshot with a corrupted physical display points later in the scanout/connector path; corruption already present in the screenshot implicates rendered framebuffer content. Attach both when they differ.
After a fix, test normal cold boot, mode changes, restart, and the original multi-monitor or workload sequence. Remove the fail-safe/blocking setting so the corrected native path is actually exercised.
Related:
Sources: