Skip to content

fix(server): stop misdiagnosing missing shared libs as missing Chromium - #746

Merged
divshekhar merged 5 commits into
reticlehq:mainfrom
SomSamantray:fix/691-chromium-missing-lib-hint
Sep 5, 2026
Merged

divshekhar merged 5 commits into
reticlehq:mainfrom
SomSamantray:fix/691-chromium-missing-lib-hint

Conversation

@SomSamantray

Copy link
Copy Markdown
Contributor

What & why

Refs #691. That issue bundles four distinct misdiagnoses in Reticle's pooled-lease
Chromium launch path. This PR fixes one of them — the rest are out of scope here
and remain open on the issue:

  • ✅ fixed by this PR: a launch failure caused by a missing OS shared library (e.g.
    libnspr4.so) is misreported as "Chromium is not installed."
  • ⬜ not fixed by this PR: Windows "package not installed" wording, a post-install
    build/version mismatch, and headed-vs-headless-only failures on Windows. Those have
    unverified root causes and are separate follow-up work.

playwrightLauncher() in packages/server/src/pool/playwright-launcher.ts catches every
chromium.launch failure with one regex
(/executable doesn.?t exist|playwright install|browsertype\.launch/i). Playwright
prefixes almost every launch error with browserType.launch:, so that regex also matches
Playwright's distinct "Host system is missing dependencies to run browsers" failure — the
browser binary is present, but the host's shared libraries are not. Users hitting that case
were told to run npx playwright install chromium, which succeeds and fixes nothing,
because the binary was never missing.

This adds a narrower check for that message, checked before the generic one, that
points at npx playwright install-deps chromium instead — pinned to the daemon's bundled
playwright version the same way the existing hint already is. A new
chromiumInstallDepsCommand sits next to the existing chromiumInstallCommand in
chromium-hint.ts, sharing a small internal pin helper.

Authored with AI pair-programming assistance (Claude Code) and reviewed by a human
before submission.

How it was verified

  • Added a test that reproduces the bug on unmodified main: a mocked chromium.launch
    rejection carrying Playwright's real "Host system is missing dependencies to run
    browsers" message was, before this fix, rewritten into the missing-binary hint (RED).
    After the fix it correctly names install-deps and no longer mentions the
    missing-binary hint (GREEN).
  • Added a regression test confirming the pre-existing missing-binary hint is unchanged,
    and a test confirming an unrelated launch failure is still rethrown as-is.
  • Added unit tests for the new chromiumInstallDepsCommand, mirroring the existing
    chromiumInstallCommand coverage (pinned and unpinned cases).
  • pnpm --filter @reticlehq/server exec vitest run on the two changed test files:
    16/16 passing.
  • pnpm --filter @reticlehq/server run typecheck: clean.
  • eslint run directly against the four changed source/test files (the full monorepo
    pnpm lint — which also builds/lints every fixture app — timed out in the sandbox this
    PR was prepared in; the scoped run against the changed files is clean, and CI runs the
    full gate regardless).

Gates run

  • pnpm lint && pnpm typecheck && pnpm test:unit (~2 min — always) — run in
    package/file-scoped form locally (see verification notes above); CI runs the
    full monorepo command.
  • pnpm test:e2e (~8 min) — not touched (no tool surface, packages/core, observer,
    or telemetry change)
  • pnpm gate:install (~15 min) — not touched (no init/vite-plugin/next/
    babel-plugin change)
  • pnpm test:e2e:desktop (~3 min) — not touched (no electron/tauri/desktop-capture
    change)
  • None of the e2e/install/desktop tiers apply to this change

Checklist

  • Every commit is signed off (git commit -s)
  • Tests added/updated (RED → GREEN); the change is covered by a test that would fail
    without it
  • No any, no free strings, no non-null !
  • No console.log or internal tracking codes left in the diff
  • Each changed file is under the 1000-line cap
  • CHANGELOG.md updated under [Unreleased]### Fixed (user-facing behavior
    change)
  • Security-affecting — n/a, no auth/redaction/trust-boundary change

SomSamantray and others added 5 commits September 3, 2026 19:18
Add chromiumInstallDepsCommand alongside the existing
chromiumInstallCommand, pinned to the bundled playwright version for
the same reason the install command is: an unpinned npx can resolve a
different playwright than the one the daemon bundles.

Prep for the playwright-launcher fix in the next commit (reticlehq#691).

Signed-off-by: Som <Som.samantray@gmail.com>
playwrightLauncher's catch-all regex (executable doesn't exist |
playwright install | browsertype\.launch) matches almost any launch
failure, because Playwright prefixes nearly all of them with
browserType.launch. That includes the distinct "Host system is
missing dependencies to run browsers" failure (missing OS shared
libraries such as libnspr4.so), which was rewritten to the
missing-binary hint telling the user to run
`npx playwright install chromium` — a command that succeeds and
fixes nothing, since the binary was never missing.

Add a narrower check for that message, checked first, that points at
`install-deps` instead. Covered by a test that reproduces the wrong
hint on current code (RED) before the fix, plus a regression test for
the untouched missing-binary case.

This addresses one of the sub-symptoms reported in reticlehq#691 (the
shared-library misdiagnosis); the other reported sub-symptoms
(Windows package-not-installed wording, post-install build mismatch,
headed-vs-headless-only Windows failures) are out of scope for this
change and are not fixed by it.

Refs reticlehq#691

Signed-off-by: Som <Som.samantray@gmail.com>
Follow-up to the previous commit: chromiumInstallCommand and
chromiumInstallDepsCommand had identical pin-or-unpinned logic,
differing only in the playwright subcommand. Extract it into a small
private helper.

Signed-off-by: Som <Som.samantray@gmail.com>
pnpm format:check flagged a double-quoted string prettier wants
single-quoted. No behavior change.

Signed-off-by: Som <Som.samantray@gmail.com>
@divshekhar
divshekhar merged commit 156e4a9 into reticlehq:main Sep 5, 2026
19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants