Skip to content

fix(win): strengthen GPU software fallback for virtual displays - #10097

Closed
innocarpe wants to merge 2 commits into
stablyai:mainfrom
innocarpe:fix/windows-gpu-software-fallback
Closed

innocarpe wants to merge 2 commits into
stablyai:mainfrom
innocarpe:fix/windows-gpu-software-fallback

Conversation

@innocarpe

@innocarpe innocarpe commented Jul 23, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Fixes Windows headless / virtual-display hosts (e.g. Sunshine + Zako) where Chromium's GPU child STATUS_BREAKPOINT-crashes on every launch and Orca never reaches a usable window.

ELI5

When Windows graphics is so broken that Orca keeps dying at startup, Orca now restarts itself in a safer "draw everything in software" mode that actually works on virtual/remote displays — and you can force that mode yourself with an environment variable.

Root cause & fix

Orca's existing crash-burst fallback relaunched with only disableHardwareAcceleration + --disable-gpu — the exact flags reporters had already tried without success — so the GPU child kept crashing. This PR routes the Windows software-GPU path through the combo proven to reach ready on those hosts: --disable-gpu + --in-process-gpu + --use-angle=swiftshader, applied before app.whenReady(). It also adds a first-launch opt-in via ORCA_SOFTWARE_GPU=1 so operators can skip the crash-burst cycle on known-bad adapters, while preserving the Windows-only, non-serve guard and the sticky-marker path.

Evidence

Validated & rebased onto latest main during a bug-bash triage on 2026-07-23. Rebase applied cleanly onto origin/main.

  • Test on branch: windows-software-gpu.test.ts exercises the fallback combo (disableHardwareAcceleration + disable-gpu + in-process-gpu + use-angle swiftshader) and ORCA_SOFTWARE_GPU env parsing.
npx vitest run --config config/vitest.config.ts src/main/startup/windows-software-gpu.test.ts
=> Test Files 1 passed (1), Tests 4 passed (4)
  • Fix reverted, test kept: re-running fails with Cannot find module './windows-software-gpu' (suite fails to load, 0 tests run) — the fix module is net-new, so the failure manifests as module-not-found rather than an assertion diff. Pass-on-branch AND fail-when-reverted = TRUE.
  • Lint clean: npx oxlint src/main/startup/windows-software-gpu.ts src/main/index.ts => exit 0.

Trade-offs

After a GPU crash burst (unchanged 3-crashes/30s window) the software path is stricter (in-process + SwiftShader), so terminal/WebGL may be slower on those already-broken hosts. Healthy GPUs are unaffected; ORCA_SOFTWARE_GPU=1 is opt-in only.

Regression risk

Low. Changes are gated behind the existing Windows-only, non-serve guard plus the crash marker or explicit env opt-in; the !envRequested && !marker early-return is preserved, so non-Windows and healthy-GPU startup paths are untouched. The passing test proves the new branch behavior.

Credit to @innocarpe (Wooseong Kim). Validated, rebased, and hardened via automated bug-bash review; original fix design preserved.

@coderabbitai

coderabbitai Bot commented Jul 23, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5d124899-e7ed-4fee-92d1-80a3066ba428

📥 Commits

Reviewing files that changed from the base of the PR and between ff01fad and 90ffcec.

📒 Files selected for processing (5)
  • src/main/index.ts
  • src/main/startup/gpu-fallback-marker.test.ts
  • src/main/startup/gpu-fallback-marker.ts
  • src/main/startup/windows-software-gpu.test.ts
  • src/main/startup/windows-software-gpu.ts

📝 Walkthrough

Walkthrough

Adds configurable Windows software-GPU activation with Chromium switches and environment parsing. Extends crash markers with notification timestamps. Updates startup fallback selection, state tracking, notice presentation, retry handling, marker acknowledgment, and crash breadcrumbs. Adds Vitest coverage for environment parsing, switch application, notice eligibility, notice content, and marker notification persistence.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Description check ⚠️ Warning The description provides a strong summary and targeted testing details but omits the required Screenshots, AI Review Report, Security Audit, and Notes sections. Add the missing template sections, mark all applicable test checks, and document cross-platform review and security audit findings.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the main change: strengthening the Windows software-GPU fallback for virtual displays.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@nwparker
nwparker force-pushed the fix/windows-gpu-software-fallback branch from 15b3a22 to 2bee28b Compare July 23, 2026 11:49
@nwparker

Copy link
Copy Markdown
Contributor

Valid but we may want to inform the user. Let me think on this a sec

@innocarpe

Copy link
Copy Markdown
Contributor Author

Sync update (8f345f947)

Address review: surface a one-shot notice when software GPU fallback engages.

@nwparker nwparker added the bug Something isn't working label Jul 27, 2026
@innocarpe
innocarpe force-pushed the fix/windows-gpu-software-fallback branch from 8f345f9 to 354711b Compare July 27, 2026 14:59
The existing crash-burst fallback only applied disableHardwareAcceleration
+ --disable-gpu. On headless virtual adapters (e.g. Sunshine Zako) Chromium
still forks a GPU child that STATUS_BREAKPOINT-crashes under those flags,
so the relaunch never reaches ready (stablyai#10093).

Apply the proven software combo (--in-process-gpu --disable-gpu
--use-angle=swiftshader) when the sticky marker engages, and allow
ORCA_SOFTWARE_GPU=1 for first-launch opt-in without waiting for a crash
burst.
Surface a one-shot info dialog when Windows software GPU / SwiftShader
fallback engages, so users know rendering is in a slower stability mode.
Marker path notifies on first activation only; env opt-in is once per session.
@innocarpe
innocarpe force-pushed the fix/windows-gpu-software-fallback branch from 354711b to 90ffcec Compare August 6, 2026 03:41
@innocarpe

Copy link
Copy Markdown
Contributor Author

Sync update (90ffcece20)

Rebase onto latest upstream/main: env software-GPU opt-in + notice; keep main post-crash non-SwiftShader switches.

@coderabbitai

coderabbitai Bot commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

@Jinwoo-H

Copy link
Copy Markdown
Contributor

Thanks @innocarpe for investigating the Windows GPU fallback path. Merged fix #11295 now owns this behavior on current main and deliberately avoids the SwiftShader/in-process combination proposed here, which would broaden privileged parsing of untrusted WebGL content. We will retain your diagnosis as historical credit and request no rebase, retest, or other follow-up. Closing this superseded branch.

@Jinwoo-H Jinwoo-H closed this Aug 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants