Skip to content
Claudezilla

Troubleshooting

Common Errors

Section titled “Common Errors”

TAB_CLOSED

Section titled “TAB_CLOSED”
TAB_CLOSED: Tab 42 no longer exists

The tab was closed (by the user, another agent, or orphan cleanup) between when you obtained the tab ID and when you tried to use it.

Fix: Call firefox_get_tabs to get current tab IDs, then retry your operation with a valid tab.

POOL_FULL

Section titled “POOL_FULL”
POOL_FULL: Tab pool is full (12/12). Close a tab first or use mercy system.

All 12 tab slots are occupied and your agent has no tabs of its own to evict.

Fix — Mercy system workflow:

  1. Call firefox_request_tab_space to queue your request.
  2. Wait briefly, then call firefox_get_slot_requests to check for youHaveReservation: true.
  3. If another agent grants space (or a tab is closed), you will get a 30-second reservation.
  4. Call firefox_create_window during the reservation window.

If you own existing tabs, close one with firefox_close_tab before opening a new one.

MUTEX_BUSY

Section titled “MUTEX_BUSY”
MUTEX_BUSY: Screenshot mutex held by another agent.
  Holder: agent_ec2e...
  Held for: 6234ms

Another Claude session is currently capturing a screenshot. The mutex prevents tab-switching collisions during captureVisibleTab.

Fix:

  • Use firefox_get_page_state instead — it returns structured JSON data without needing the screenshot mutex and is faster.
  • If you need a visual screenshot, wait a few seconds and retry.

CONTENT_SCRIPT_ERROR

Section titled “CONTENT_SCRIPT_ERROR”
CONTENT_SCRIPT_ERROR: Cannot access this page type

The content script cannot be injected into the current page. This happens with non-HTML pages such as JSON responses, binary files, about: pages, PDF viewers, and browser-internal pages.

Fix:

  • For JSON/API responses, use firefox_evaluate to read document.body.innerText directly.
  • For about: pages, most operations other than getTabs and closeTab are unavailable.
  • Navigate to an HTML page before attempting DOM operations.

OWNERSHIP

Section titled “OWNERSHIP”
OWNERSHIP: Cannot navigate tab 42 (owned by agent_e7f8...)

You are trying to navigate, close, or modify a tab that belongs to a different Claude session.

Fix: Each agent can only control tabs it created. Call firefox_get_tabs to see which tabs you own (check the ownerId field), and only operate on those.

Connection Issues

Section titled “Connection Issues”

Extension Not Connecting to Host

Section titled “Extension Not Connecting to Host”

Symptoms: Clicking the Claudezilla toolbar icon shows “Disconnected” or “Host not found.”

Checklist:

  1. Host manifest exists:

    Terminal window
    cat ~/.mozilla/native-messaging-hosts/claudezilla.json

    Verify the path field points to the correct absolute path of host/index.js.

  2. Host is executable:

    Terminal window
    ls -la /path/to/claudezilla/host/index.js

    The first line must be #!/opt/homebrew/bin/node (macOS) or #!/usr/bin/env node (Linux). The file must be executable (chmod +x).

  3. Node.js is available at the path specified in the shebang line.

  4. Re-run the installer to regenerate the manifest with correct paths:

    Terminal window
    ./install/install-macos.sh   # or install-linux.sh

  5. Restart Firefox after installing or updating the manifest.

MCP Server Not Connecting to Host

Section titled “MCP Server Not Connecting to Host”

Symptoms: Claude Code tools return connection errors or timeouts.

Checklist:

  1. Host is running: The native host only starts when the Firefox extension connects. Open Firefox and verify the extension shows “Connected” in the popup.

  2. Socket exists: Check that the Unix socket file is present:

    Terminal window
    ls -la /tmp/claudezilla-* 2>/dev/null || ls -la $XDG_RUNTIME_DIR/claudezilla-* 2>/dev/null

  3. Auth token is readable: The MCP server needs to read the auth token written by the host:

    Terminal window
    ls -la /tmp/claudezilla-auth-* 2>/dev/null

  4. Run diagnostics: Use the built-in diagnostic tool:

    firefox_diagnose

    This checks the extension connection, socket availability, auth token, and host version.

Tools Timing Out

Section titled “Tools Timing Out”

Symptoms: MCP tool calls hang for 150 seconds then return a timeout error.

Causes:

  • The page is taking too long to load (network issues, heavy JavaScript).
  • The screenshot readiness detection is waiting for resources that will never load.

Fix:

  • Pass a shorter timeout value (e.g., timeout: 10000 for 10 seconds).
  • For screenshots, use skipReadiness: true to bypass page readiness detection.
  • For page content, use firefox_get_page_state which is typically faster than firefox_get_content.