How to Troubleshoot Browser Launch Failures When Using wigolo on Linux

Run wigolo warmup --browser to download the Playwright binary and install missing system libraries such as libnss3 and libatk-1.0, then verify the fix with wigolo doctor.

When scraping JavaScript-heavy pages on Linux distributions, KnockOutEZ/wigolo leverages a bundled Playwright browser engine that depends on specific shared system libraries. If these dependencies are missing from your environment, the browser acquisition logic fails and the fetch router falls back to plain HTTP requests, often returning incomplete content or triggering errors.

Understanding Why wigolo Browser Launch Failures Occur on Linux

The Playwright browser engine bundled with wigolo requires several system libraries to function on Linux, including libnss3, libatk-1.0, libx11, and libasound2. When wigolo attempts to fetch a page that requires JavaScript rendering, the logic in src/fetch/browser-acquire.ts tries to launch the browser binary. If the binary cannot execute due to missing dependencies, the code catches the failure and emits an error message containing a hint to run wigolo warmup --browser, as documented in docs/troubleshooting.md (lines 15-16) and verified by unit tests in tests/unit/fetch/browser-acquire.test.ts (lines 258-262).

Step-by-Step Troubleshooting Workflow

1. Diagnose the Current State with wigolo doctor

Before attempting fixes, determine exactly which component is failing. The built-in doctor command labels the browser tier status and displays actionable hints.

wigolo doctor

If the browser tier reports as failed, the output will suggest running the warm-up command.

2. Execute the Browser Warm-up Command

The wigolo warmup --browser command, implemented in src/cli/warmup.js, downloads the Playwright binary (approximately 0.5–1 GB) and executes a post-install script to install required OS libraries. The script automatically escalates with sudo when possible.

wigolo warmup --browser

If the command succeeds, the browser engine is ready. If it fails due to permission restrictions, it prints the exact manual installation command required.

3. Manually Install Dependencies in Restricted Environments

On minimal containers or custom Linux images where sudo is unavailable, you must install the libraries manually. Copy the command suggested by the warm-up output, or run the standard package installation for Debian/Ubuntu-based systems:

sudo apt-get install -y libnss3 libatk1.0-0 libx11-6 libasound2

After manual installation, re-run the warm-up command to verify the engine can start:

wigolo warmup --browser

4. Use a Mirror for Faster Binary Downloads

If the Playwright binary download is slow or blocked by network restrictions, set the PLAYWRIGHT_DOWNLOAD_HOST environment variable to a faster mirror before running the warm-up step, as noted in docs/troubleshooting.md (lines 24-25).

export PLAYWRIGHT_DOWNLOAD_HOST=https://npm.taobao.org/mirrors/playwright
wigolo warmup --browser

5. Enable Debug Logging for Detailed Diagnostics

When the browser still fails to launch, increase log verbosity to see the exact system call that failed. Set LOG_LEVEL=debug and LOG_FORMAT=text to output detailed logs to stderr, which you can redirect to a file for analysis.

LOG_LEVEL=debug LOG_FORMAT=text wigolo warmup --browser 2>wigolo-debug.log

All logs are written to stderr according to the implementation in the error handling logic.

ARM64 Linux Limitations and Semantic Embedding Fallbacks

On Linux ARM64 architectures, the Playwright browser binary itself functions correctly, but the semantic embedding model is not yet available. Consequently, features like find_similar and semantic ranking automatically fall back to keyword matching, as documented in docs/troubleshooting.md (lines 63-64). This limitation does not affect standard browser rendering but may impact content analysis accuracy.

Verifying the Installation

After completing the warm-up process, confirm the browser tier is healthy:

wigolo doctor

A successful status indicates that src/fetch/browser-acquire.ts can successfully launch the Playwright engine and that wigolo will use full JavaScript rendering instead of falling back to plain HTTP fetch.

Summary

• Missing system libraries (libnss3, libatk-1.0, libx11, libasound2) are the primary cause of browser launch failures on Linux.
• wigolo warmup --browser downloads the Playwright binary and attempts to install dependencies automatically via src/cli/warmup.js.
• Manual installation is required when running in containers or without sudo privileges.
• PLAYWRIGHT_DOWNLOAD_HOST can speed up downloads in restricted network environments.
• Debug logs (LOG_LEVEL=debug) reveal the exact system call failures for advanced troubleshooting.
• ARM64 systems support browser rendering but lack semantic embedding capabilities.

Frequently Asked Questions

What system libraries does wigolo require on Linux for browser rendering?

wigolo requires libnss3, libatk1.0-0, libx11-6, and libasound2 (or equivalent packages for your distribution). These dependencies are documented in docs/troubleshooting.md and are installed automatically by wigolo warmup --browser when sudo is available.

How do I fix browser launch errors when running wigolo in Docker containers?

In minimal container images without sudo, manually install the required libraries using your package manager before running wigolo. For Debian-based containers, run apt-get install -y libnss3 libatk1.0-0 libx11-6 libasound2, then execute wigolo warmup --browser to verify the binary can start.

Why does wigolo fall back to HTTP fetch instead of rendering JavaScript?

When the Playwright browser fails to launch due to missing dependencies or permission issues, the acquisition logic in src/fetch/browser-acquire.ts catches the error and signals the fetch router to fall back to plain HTTP. This fallback avoids crashing the application but may retrieve incomplete content from JavaScript-heavy sites.

How can I verify that the browser engine is working correctly?

Run wigolo doctor to check the browser tier status. If it reports as failed, execute wigolo warmup --browser and check for successful completion messages. For detailed verification, set LOG_LEVEL=debug and inspect the logs to confirm the Playwright process starts without system library errors.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}