Skip to content

bug: obs-browser: when CEF never finishes starting, quit hangs forever and browser sources stay blank without a warning #3833

Closed

Description

@vpacher

Location

plugins/obs-browser/obs-browser-plugin.cpp (submodule obs-rust/obs-browser at 463e16b):

  • obs_module_unload(), Linux path without ENABLE_BROWSER_QT_LOOP: os_event_wait(cef_initialized_event) has no time limit. The manager thread signals that event only when BrowserInit() (and so CefInitialize()) returns.
  • BrowserManagerThread() / BrowserInit(): when CefInitialize() does not return, nothing is logged and nothing is shown to the user.

Found while investigating #3739.

Class

Hang at quit, and a silent loss of a feature. Only trusted local input reaches it: the installed CEF and the user's own scene collection.

How it is reached

Seen on Arch Linux (Hyprland, Wayland) with the AUR obs-rust-git package built against the Arch cef package 152.0.6. With that CEF, CefInitialize() does not return. gdb shows BrowserInit() entered, and neither the context-initialized callback nor the line after BrowserInit() reached in 40 s. Why that CEF stalls is not known; the same build against cef 154.0.34 works.

Then:

  1. A browser source never renders, not even a local data: page. The log has no error.
  2. At quit, obs_shutdown() unloads obs-browser and the main thread waits forever:
    obs_shutdown() -> free_module(obs-browser) -> obs_module_unload()
      obs-browser-plugin.cpp:1015  os_event_wait(cef_initialized_event)
    
    The window is gone, obs-studio-rust-gui and the obs-browser-page zygote processes stay, and SIGHUP or SIGTERM do not end them. The next start reports that OBS is already running.

Measured with the same build, same scene, quit by window close and by SIGHUP:

cef Browser source Quit
152.0.6 blank hangs, 4 of 4
154.0.34 renders 1 to 2 s, 4 of 4

With 152, every other run with a browser source hung too (16 more runs, with the variations below).

The stall does not depend on the CEF sandbox (also with the sandbox off), on Wayland (also with XWayland), on the session D-Bus (also without it) or on the GPU (also with --disable-gpu).

The wait was added by 0c3b700 (10-17) to coordinate unload with a CEF that is still starting. That coordination is correct and must stay. Before it, obs_module_unload() called manager_thread.join(), which hangs in the same way on a CEF that does not return.

Proposed fix and failing test

Two PRs, in this order:

  1. Quit does not wait forever. Wait for cef_initialized_event with a time limit (os_event_timedwait). When the limit passes, log an error, do not post the quit task, do not join the manager thread, and let OBS shut down. Keep the 0c3b700 behavior for every CEF that starts or fails within the limit. Open point: the manager thread is still inside CefInitialize() when the process exits, so library destructors run while it is there. The test must show that the exit does not crash, and that the obs-browser-page helper processes end too. If a normal exit is not safe, end the process with _exit() after the shutdown of everything else, and log why.
  2. The user learns that CEF did not start. If BrowserInit() has not returned some seconds after the first browser source or dock asks for CEF, log an error that names the CEF version, and show one warning that browser sources and docks will not work. A failed CefInitialize() (the existing "CEF failed to initialize" path) gets the same warning.

RED for 1: a variant of tests/startup_shutdown.py in which CefInitialize() does not return. CEF cannot be made to stall on demand, so the test interposes one symbol, cef_initialize, with an LD_PRELOAD shim that blocks until the test releases it. Everything else stays real. Without the fix, OBS shutdown does not finish within the test's bound; with the fix, it finishes, and the log has the error. The existing initialization_failure.py and immediate-unload cases must still pass.

RED for 2: the same shim, and an assertion that the error and the warning appear once, within the limit.

What is still open: the time limits, and whether the warning is a log line only or also a dialog.

Activity

  1. zackees commented on Nov 7, 2026

    @zackees
    Member

    Claiming: #3833 (pool slot obs-studio3).

    1. Add a failing deterministic stalled-initialization shutdown test, preserving normal and slow startup coverage.
    2. Implement bounded shutdown and a startup warning, with explicit blocked-thread and helper cleanup semantics in obs-browser.
    3. Open the browser PR and parent submodule/feature-ledger PR; first RED PR expected this session.

    Decisions: use a log warning for the startup failure, so headless use is covered without requiring a modal dialog. No CEF support-version policy changes. Refs #3739; not taking that issue.

  2. zackees commented on Nov 7, 2026

    @zackees
    Member

    /ready

    The pool assignment authorizes implementation. Deterministic RED: interpose cef_initialize and block it; require bounded quit, a startup warning, helper cleanup, and normal/slow-init controls. CEF version support decisions remain out of scope.

  3. moved this from In progress to Ready in obs-rust Multiviewon Nov 8, 2026
  4. rdoupe commented on Nov 15, 2026

    @rdoupe
    Collaborator

    Fixed by #3846 together with obs-rust/obs-browser#19 (both merged 2026-11-07): stalled CEF startup now has a bounded quit and a startup warning. They said Refs, so this stayed open. Closing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingreadyMeets the definition of Ready; claimable

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions