Skip to main content
The official figranium NPM package is retired and is not supported from v0.13 onward. The “NPM” fixes below apply only to legacy installs; on v0.13+, use Docker or a source install.
Common issues and their solutions when running Figranium.

​
Browser fails to launch

Error: Failed to launch browser: Chromium revision is not downloaded.
  • Cause: Playwright needs specific browser binaries that aren’t installed.
  • Fix (Docker): Rebuild the image to re-download browsers:
  • Fix (NPM):
Error: Protocol error (Target.detachFromTarget): Target closed.
  • Cause: The browser crashed, usually due to insufficient memory or shared memory limits.
  • Fix:
    • Increase Docker memory limits in docker-compose.yml:
    • Figranium already passes --disable-dev-shm-usage by default, which helps on constrained systems.
Error: spawn ENOMEM or Cannot allocate memory
  • Cause: The host machine is out of RAM.
  • Fix: Restart Docker, increase swap space, or upgrade your instance.

​
Proxies not working

Error: ERR_PROXY_CONNECTION_FAILED or net::ERR_TUNNEL_CONNECTION_FAILED
  • Cause: Invalid proxy credentials, wrong format, or network firewall blocking the connection.
  • Fix:
    1. Verify the proxy format: http://user:pass@host:port or socks5://host:port.
    2. Test the proxy from your server: curl --proxy "http://host:port" https://ifconfig.me.
    3. Check your server’s outbound firewall rules.
  • Cause: The proxy is configured but the task doesn’t have it enabled.
  • Fix:
    • Open the task in the Editor > Settings > Proxy tab and confirm proxy use is toggled on.
    • Check Settings > Proxies to ensure at least one proxy is marked as active/default.

​
Element not found

Error: Timeout 30000ms exceeded while waiting for selector ".foo"
  • Cause 1: The selector is wrong — the element doesn’t match the CSS you provided.
    • Fix: Use Headful Debugging to open the browser and inspect the live page. Right-click > Inspect to find the correct selector.
  • Cause 2: The element loads asynchronously after the page renders.
    • Fix: Add a Wait action (e.g., 2000ms) before the failing action, or use a Wait for Selector action explicitly targeting the element.
  • Cause 3: The element is inside a <iframe>.
    • Note: Figranium does not currently support cross-origin iframes. Same-origin iframes may work via JavaScript execution.
  • Cause 4: The element is inside a Shadow DOM.
    • Fix: Enable Shadow DOM support in task settings, then use deep selectors.
  • Cause 5: The element is only visible on desktop and the viewport is too small.
    • Fix: In task settings, set a larger viewport width (e.g., 1920x1080).

​
Dashboard session expires frequently

  • Cause 1: Sessions expire after 7 days. This is expected behavior — log in again to start a new session.
  • Cause 2: SESSION_SECRET changes on every server restart (auto-generated secret).
    • Fix: Set a static SESSION_SECRET in your .env file:
  • Cause 3: SESSION_COOKIE_SECURE=true is set but you’re accessing via HTTP.
    • Fix: Either access via HTTPS, or set SESSION_COOKIE_SECURE=false for HTTP-only setups.

​
CAPTCHA / Bot Detection

  • Cause: The target website detected automated browser behavior, or served a CAPTCHA challenge.
  • Fix:
    1. If a supported CAPTCHA renders (reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile), drop a Solve Captcha block at that step, or toggle Auto-Solve Captchas in the task’s Behavior tab. Figranium routes solves through a configured YesCaptcha/AntiCaptcha-compatible endpoint first and falls back to the built-in local model. See CAPTCHA Solving for setup and environment variables.
    2. Enable Stealth Mode options in the Task Editor (natural typing, idle movements, etc.).
    3. Use high-quality Residential Proxies rather than datacenter IPs.
    4. Rotate User Agents in Settings > System > User Agent.
    5. Add random Wait actions (500 to 2000ms) between interactions.
    6. Avoid actions that no human would do (instant form fill, no mouse movement).

​
Task runs successfully in headful mode but fails headless

  • Cause: Some sites detect headless browsers via JavaScript (e.g., navigator.webdriver).
  • Fix:
    • Ensure Stealth Plugin is active (it is by default in Figranium).
    • Check if the failure is viewport-related (some sites show different content at different sizes). Set a realistic viewport in task settings.
    • Compare the page HTML in both modes using javascript blocks that return document.documentElement.outerHTML.

​
Data extraction returns empty or wrong results

  • Cause 1: The extraction script runs before dynamic content finishes loading.
    • Fix: Add Wait or Wait for Selector actions before your final extraction step.
  • Cause 2: The extraction script has a bug.
    • Fix: Use a JavaScript action in the middle of your task to return document.querySelector(".target")?.innerText and inspect the result in the execution logs.
  • Cause 3: The page structure changed.
    • Fix: Open the page in headful mode and re-inspect the selectors.

​
Execution hangs and never completes

  • Cause 1: A While loop with a condition that’s always true.
    • Fix: Add a counter variable and a Stop block to break the loop.
  • Cause 2: A Wait for Selector waiting for an element that never appears.
    • Fix: Wrap it in an On Error block with a fallback, or reduce the timeout.
  • Cause 3: A download action waiting for a file that never triggers.
    • Fix: Check that the target element actually initiates a download.
  • Note: Since v0.19, non-headful runs are stopped after EXECUTION_TIMEOUT_MS (15 minutes by default) and return 504 EXECUTION_TIMEOUT. Raise the value in your .env if a task legitimately needs longer. See Configuration.

​
Executions return 503 (RESOURCE_CAPACITY_EXCEEDED)

  • Cause: Figranium’s host-aware resource protection limits how many browsers run at once. Extra runs wait in a queue, which pauses when memory or CPU is under pressure. When the queue is full (50 by default) or a run waits more than 10 minutes, the request is rejected with 503.
  • Fix:
    • Retry after the number of seconds in the Retry-After header.
    • Check protection in GET /api/health to see maxConcurrent, pressure, active, and queued.
    • Spread out scheduled tasks, add memory to the host or container, or adjust MAX_CONCURRENT_EXECUTIONS, MAX_EXECUTION_QUEUE, and EXECUTION_QUEUE_TIMEOUT_MS. See Host-aware resource protection.

​
PostgreSQL connection fails

  • Cause: Database connection environment variables are wrong or the database is unreachable.
  • Fix:
    • Verify DB_POSTGRESDB_HOST, DB_POSTGRESDB_PORT, DB_POSTGRESDB_USER, DB_POSTGRESDB_PASSWORD in your .env.
    • Test connectivity: psql -h $DB_POSTGRESDB_HOST -U $DB_POSTGRESDB_USER.
    • Check that the database and user exist with correct permissions.
    • Figranium will fall back to file-based storage if the DB is unavailable — check server logs for the fallback warning.

​
API requests return 401 or 403

  • 401 Unauthorized: Missing or invalid API key.
    • Fix: Include the API key in the X-API-Key header. Retrieve it from Settings > API Keys.
  • 403 Forbidden: Your IP is not in the allowlist.
    • Fix: Add your IP to Settings > System > Allowed IPs, or clear the allowlist to allow all IPs.

​
API key save returns 400 (API_KEY_TOO_LONG)

  • Cause: The API key you provided exceeds the 512-character limit for the system API key.
  • Fix: Use a shorter key. Generated keys are well under this limit — if you hit it, check for accidental whitespace or extra characters in your input.

​
Headful viewer shows “Connecting…” then “Disconnected” on Apple Silicon Macs

  • Cause: An older Figranium image was published as linux/amd64 only. On Apple Silicon (M1–M4) Macs, Docker Desktop pulls that image and runs it under QEMU emulation, where Xvfb and x11vnc are prone to crashing seconds after start. The noVNC viewer connects briefly, then drops. The selector-picker SSE stream fails the same way because it depends on the same headful browser session.
  • Fix: Update to the latest image. Figranium is now published as a true multi-architecture image (linux/amd64 and linux/arm64), so Apple Silicon pulls a native ARM64 build:
    Confirm the pulled architecture matches your host:
    On Apple Silicon this should print arm64. If it prints amd64, your Docker client is not selecting the ARM variant — run docker compose pull --platform linux/arm64 to force it.
  • If the viewer still drops: Xvfb, x11vnc, and websockify each run inside a restart loop, and the noVNC page auto-reconnects with backoff. Look at the per-process logs to see which component is crashing:
    A quick post-connect drop is labeled “Browser session crashed, retrying…” in the viewer, distinguishing a real crash from a routine reconnect.

​
Server crashes on Render with ERR_ERL_UNEXPECTED_X_FORWARDED_FOR

  • Cause: When Figranium runs behind a reverse proxy (such as Render’s edge), incoming requests carry an X-Forwarded-For header. The rate limiter rejects this header unless the server is explicitly told to trust the proxy, causing the process to crash on the first authenticated request.
  • Fix: On Render, no action is needed — the server detects the platform-provided RENDER=true environment variable and enables trust proxy automatically. On other proxied deployments (Nginx, Caddy, AWS ALB, Fly.io), set TRUST_PROXY=true in your environment:
    See Reverse proxy and TRUST_PROXY for the security implications of trusting forwarded headers.

​
Getting More Help

Execution Logs

Check the execution logs in the Executions tab for detailed error messages.

Headful Browser

Use the Headful Browser to observe your task running in real time.

GitHub Issues

File issues at the Figranium GitHub repository.