Troubleshoot Web Browsers on OpenBSD

Synopsis #

Firefox and Chromium are maintained as OpenBSD packages and include platform-specific launchers, sandbox policy, and package documentation. Check the package, profile, resource limits, and graphical session before trying launch flags. Keep the browser sandbox enabled. This guide covers package state, profiles, login-class limits, session services, graphics, and recording permissions.

Browser profiles contain credentials, cookies, history, and encryption material. Back up a profile before moving or modifying it, and do not attach a complete profile to a public bug report.

Read the Installed Package Documentation #

Confirm the installed package and read its current README:

pkg_info | grep -E 'chromium|firefox'
  # Identify the installed browser package
ls /usr/local/share/doc/pkg-readmes | grep -E 'chromium|firefox'
  # Identify browser-specific integration notes when installed

README names follow installed package stems and not every package installs one. Read each matching file and retain the installation messages printed by pkg_add. List the complete directory when the expected name differs:

ls /usr/local/share/doc/pkg-readmes

Update the base system and packages through the normal upgrade workflow before diagnosing a failure already corrected by maintainers.

Start from a Terminal #

Start the browser from an xterm or another terminal inside the graphical session:

firefox

or:

chrome

Preserve the first error and the preceding lines. Later messages are often consequences of the initial failure. Confirm that the same command resolves to the packaged launcher with which(1) :

which firefox

Shell aliases, locally installed wrappers, and stale desktop launchers can bypass package integration.

Separate Profile Failures from System Failures #

For Firefox, open the profile manager:

firefox -ProfileManager

Create a temporary profile and reproduce the failure without extensions or imported settings. Safe mode provides a second narrow test:

firefox -safe-mode

Do not delete the original profile. A failure limited to one profile normally points to an extension, preference, cache, or damaged profile database rather than an OpenBSD platform defect.

Chromium can be tested with a securely created temporary data directory:

test_profile=$(mktemp -d /tmp/chromium-test.XXXXXXXXXX)
  # Create a private temporary profile directory
chrome --user-data-dir="$test_profile"
  # Reproduce the failure without the normal profile

Remove only the recorded temporary directory after the browser exits. Do not point this option at the normal profile while another browser process is running.

Check Resource Limits #

Packaged browser launchers may check or raise required soft limits. Review the launcher’s warning and the installed package README before changing login.conf(5) .

Display the current shell limits:

ulimit -a

If the package documentation requires a login-class change, edit the appropriate local class, rebuild the database with cap_mkdb(1) , log out completely, and log in again. Do not copy numeric limits from an old release or a different browser. Raising every limit hides which resource ran out and weakens the limits set by the administrator.

Confirm the Graphical Session Services #

Desktop environments normally start a D-Bus session. Minimal window-manager sessions may require the startup method documented by the installed dbus package:

less /usr/local/share/doc/pkg-readmes/dbus

Apply that package-specific session configuration rather than starting multiple session buses from shell initialization files. Compare a failing desktop launcher with a working terminal launch to identify environment differences.

Isolate Graphics Problems #

Confirm the attached graphics driver and inspect browser diagnostics:

dmesg | grep -Ei 'drm|inteldrm|amdgpu|radeondrm'

Firefox exposes graphics decisions in about:support; Chromium exposes them in chrome://gpu. Record the compositor, driver, and reported failure reason. Test package-documented acceleration settings one at a time and retain only a setting that fixes a reproduced problem.

Do not add Linux GPU switches, replace Xenocara libraries, or disable the browser sandbox as a general graphics fix.

Diagnose Downloads and External Handlers #

OpenBSD browser packages use pledge(2) and unveil(2) . The package README identifies writable download directories and the policy files used for external handlers.

Create the documented download directory before testing it:

install -d -m 700 ~/Downloads

Extend unveil policy only for a specific required path and permission. Preserve a copy of the package-provided file, document the local change, and retest after package updates. Do not leave the unveil policy set to disable as a workaround.

Enable Audio, Microphone, or Camera Access #

First verify ordinary audio playback outside the browser. Microphone and camera access require OpenBSD recording controls, and a camera device also requires deliberate filesystem access for the logged-in account. Configure Multimedia on OpenBSD documents the complete procedure.

When a browser works except for a conferencing site, separate site permission, global recording policy, device-node access, and browser package policy. Do not make /dev/video* world-accessible.

Prepare a Useful Report #

Record:

  • OpenBSD release and architecture;
  • exact browser package version;
  • whether a new profile reproduces the problem;
  • terminal error output;
  • relevant dmesg graphics lines;
  • the graphics diagnostics page;
  • the smallest reproducible URL or local test case;
  • local launcher, login-class, pledge, or unveil changes.

Remove browsing history, tokens, account identifiers, private URLs, and profile contents before sharing evidence. The installed package README states the preferred debugging path for the maintained port.

Report a bug