Troubleshooting

Common issues and their solutions when using Playwriter.

Installation Issues

"playwright_ex driver not found"

The Playwright Node.js driver isn't installed.

Solution:

mix playwright.install

Or manually:

cd deps/playwright_ex
npm install
npx playwright install chromium

"Browser executable not found"

Playwright browsers aren't installed.

Solution:

npx playwright install chromium
# Or for all browsers:
npx playwright install

Missing System Dependencies (Linux)

Chromium needs certain system libraries.

Solution:

# Debian/Ubuntu
npx playwright install-deps chromium

# Or manually
sudo apt-get install -y libwoff1 libopus0 libwebpdemux2 libgudev-1.0-0 \
  libsecret-1-0 libhyphen0 libgdk-pixbuf2.0-0 libegl1 libnotify4 libxslt1.1 \
  libevent-2.1-7 libgles2 libvpx7 libxcomposite1 libatk1.0-0 libatk-bridge2.0-0 \
  libepoxy0 libgtk-3-0 libharfbuzz-icu0

Connection Issues

"Connection refused" (Remote Mode)

The Playwright server isn't running or isn't accessible.

Checklist:

Is the server running?

# On Windows
npx playwright run-server --port 3337

Is the port open?
```
# Windows
netstat -an | findstr 3337
```
Is Windows Firewall blocking it?
- Allow Node.js through firewall
- Or temporarily disable for testing

Is the endpoint correct?

# Try explicit endpoint
Playwriter.fetch_html(url,
  mode: :remote,
  ws_endpoint: "ws://localhost:3337/"
)

"Discovery failed"

Auto-discovery can't find a Playwright server.

Debug steps:

# Check what discovery tries
{:ok, endpoint} = Playwriter.Server.Discovery.discover(timeout: 10_000)

# Check WSL gateway IP
{:ok, ip} = Playwriter.Server.Discovery.get_wsl2_host_ip()
IO.puts("Gateway IP: #{ip}")

# Try connecting manually
{:ok, html} = Playwriter.fetch_html(url,
  mode: :remote,
  ws_endpoint: "ws://#{ip}:3337/"
)

"WebSocket timeout"

Connection established but operations time out.

Solutions:

Increase timeout:

Playwriter.fetch_html(url, timeout: 120_000)

Check network latency between WSL and Windows
Ensure server isn't overloaded

Browser Issues

Browser doesn't appear (Remote Mode)

Ensure headless is false:

Playwriter.fetch_html(url, mode: :remote, headless: false)

Check browser is installed on Windows:

npx playwright install chromium

Wrong browser type

Specify browser:

Playwriter.fetch_html(url, browser_type: :firefox)

Install the browser:

npx playwright install firefox
npx playwright install webkit

"Browser closed unexpectedly"

The browser crashed or was killed.

Possible causes:

Out of memory
Browser version incompatibility
Corrupted browser installation

Solutions:

# Reinstall browsers
npx playwright install --force

# Use different browser
Playwriter.fetch_html(url, browser_type: :firefox)

Navigation Issues

Page doesn't load completely

JavaScript content not rendered.

Solution - wait longer:

Playwriter.with_browser([], fn ctx ->
  :ok = Playwriter.goto(ctx, url)
  Process.sleep(3000)  # Wait for JS
  {:ok, html} = Playwriter.content(ctx)
  html
end)

Solution - use wait_until:

:ok = Playwriter.goto(ctx, url, wait_until: :networkidle)

"Navigation timeout"

Page takes too long to load.

Solutions:

# Increase navigation timeout
:ok = Playwriter.goto(ctx, url, timeout: 60_000)

# Or don't wait for full load
:ok = Playwriter.goto(ctx, url, wait_until: :domcontentloaded)

SSL/Certificate errors

Site has invalid certificates.

Solution:

Playwriter.with_browser([ignore_https_errors: true], fn ctx ->
  :ok = Playwriter.goto(ctx, "https://self-signed.example.com")
end)

Element Interaction Issues

"Element not found"

Selector doesn't match any element.

Debug steps:

Verify selector in browser DevTools
Check if element is in an iframe

Wait for element to appear:

Process.sleep(1000)
:ok = Playwriter.click(ctx, selector)

"Element not clickable"

Element is covered or not visible.

Solutions:

Scroll element into view
Wait for animations to complete
Check for overlays/modals

"Element detached"

Page changed while interacting.

Solution:

# Re-query after navigation
:ok = Playwriter.goto(ctx, url)
Process.sleep(500)
:ok = Playwriter.click(ctx, selector)

Performance Issues

Slow scraping

Tips:

Use headless mode:

Playwriter.fetch_html(url, headless: true)

Use local transport for production:

Playwriter.fetch_html(url, mode: :local)

Disable images (if supported):
```
# Custom context options
```
Reuse browser sessions for multiple pages

Memory issues

Many browser instances consuming memory.

Solutions:

Ensure sessions are closed properly
Use with_browser/2 which handles cleanup
Limit concurrent sessions
Monitor with :observer.start()

WSL-Specific Issues

Can't reach Windows from WSL

Check WSL version:

wsl.exe -l -v

WSL 2 networking:

# Get Windows host IP
cat /etc/resolv.conf | grep nameserver

WSL 1 networking:

Should use localhost directly

Slow network between WSL and Windows

Solutions:

Use localhost instead of IP when possible
Consider WSL 1 for lower latency
Run Elixir natively on Windows if latency is critical

Debugging Tips

Enable verbose logging

# In config/dev.exs
config :logger, level: :debug

Inspect session state

Playwriter.with_browser([], fn ctx ->
  # Get session state
  state = :sys.get_state(ctx.session)
  IO.inspect(state, label: "Session state")

  :ok
end)

Take debug screenshots

Playwriter.with_browser([headless: false], fn ctx ->
  :ok = Playwriter.goto(ctx, url)

  # Before action
  {:ok, before} = Playwriter.screenshot(ctx)
  File.write!("/tmp/before.png", before)

  result = Playwriter.click(ctx, selector)

  # After action (or on error)
  {:ok, after_shot} = Playwriter.screenshot(ctx)
  File.write!("/tmp/after.png", after_shot)

  result
end)

Interactive debugging

# Pause to inspect browser
Playwriter.with_browser([mode: :remote, headless: false], fn ctx ->
  :ok = Playwriter.goto(ctx, url)

  IO.puts("Inspect the browser now. Press Enter to continue...")
  IO.gets("")

  {:ok, html} = Playwriter.content(ctx)
  html
end)

Getting Help

If you're still stuck:

Check existing issues: https://github.com/yourusername/playwriter/issues
Open a new issue with:
- Playwriter version (Playwriter.version())
- Elixir/OTP versions (elixir -v)
- Operating system
- Minimal reproduction code
- Full error message/stacktrace

← Previous Page Testing Guide

Next Page → Running Examples