[BUG] Missing patchright browser binary surfaces as misleading "Network error" with no guidance

[stickerdaniel]

Setup

uv run on macOS (Darwin 25.4.0, arm64), stdio + streamable-http transports, Claude Desktop / direct CLI.

What Happened

After patchright was upgraded from v1208 → v1217, all tool calls (get_conversation, send_message, etc.) failed with:

Network error. Check your connection and try again.

The actual root cause was that the new chromium binary (chromium_headless_shell-1217) was missing — only chromium_headless_shell-1208 was present in ~/.linkedin-mcp/patchright-browsers/. The underlying patchright exception was clear:

BrowserType.launch_persistent_context: Executable doesn't exist at
/Users/daniel/.linkedin-mcp/patchright-browsers/chromium_headless_shell-1217/chrome-headless-shell-mac-arm64/chrome-headless-shell

Looks like Playwright was just installed or updated.
Please run the following command to download new browsers:
    patchright install

But it surfaced to the user as a generic "Network error", sending them down the wrong debugging path.

Three distinct bugs

1. Error misclassification — linkedin_mcp_server/core/browser.py:127 catches every Exception from launch_persistent_context() and re-raises as NetworkError. A missing browser binary is not a network problem.
2. Stale readiness check skips reinstall — bootstrap.py:browser_setup_ready() (line 154) returns True based on metadata file + non-empty dir, so after a patchright upgrade the old metadata still satisfies the check even though the new binary is missing. start_background_browser_setup_if_needed() therefore never reinstalls.
3. Server mode never reinstalls — ensure_browser_installed() is only called in cli_main.py for --login and --status. Server startup relies on the broken readiness check above, so users hit the misclassified runtime error instead of getting an auto-reinstall.

Steps to Reproduce

1. Run server with patchright vN browsers installed and a populated metadata file at ~/.linkedin-mcp/patchright-browsers/.install-metadata.json.
2. Upgrade patchright to vN+1 (e.g., a lockfile refresh that bumps patchright).
3. Start server: uv run -m linkedin_mcp_server --transport streamable-http.
4. Call any tool. It fails with Network error. Check your connection and try again..

Faster repro without an upgrade:

rm -rf ~/.linkedin-mcp/patchright-browsers/chromium_headless_shell-*
# leave .install-metadata.json in place
uv run -m linkedin_mcp_server --transport streamable-http --log-level DEBUG
# call any tool -> "Network error"

Logs

NetworkError: Failed to start browser: BrowserType.launch_persistent_context:
Executable doesn't exist at .../chromium_headless_shell-1217/chrome-headless-shell-mac-arm64/chrome-headless-shell

Looks like Playwright was just installed or updated.
Please run the following command to download new browsers:
    patchright install

Stack trace bottoms out at core/browser.py:127 -> raise NetworkError(...) from e.

Suggested fix

• Add a dedicated BrowserNotInstalledError (or similar) in core/exceptions.py.
• In core/browser.py:start(), detect the patchright "Executable doesn't exist" / "Please run the following command" patterns and raise the specific error.
• In error_handler.py, map it to a clear remediation message like: Patchright Chromium binary is missing. Run 'uv run patchright install chromium' (or restart the server to auto-install).
• In bootstrap.py:browser_setup_ready(), validate that an actual chromium binary exists under the configured PLAYWRIGHT_BROWSERS_PATH matching the currently-installed patchright driver version, not just the presence of the metadata file. On mismatch, drop the metadata so start_background_browser_setup_if_needed() triggers a reinstall.
• Optionally: run ensure_browser_installed() (or its async equivalent) in server mode too, on first tool call if readiness check fails.

Environment

• linkedin-scraper-mcp 4.6.1 (current main)
• patchright (uv resolved a version between cache yq-7_AN21rdSw7Ol3nTg_ and the project workspace)
• Python 3.12, macOS arm64