Troubleshooting

​

1. Browser fails to launch

• Cause: Playwright needs specific browser binaries that aren’t installed.
• Fix (Docker): Rebuild the image to re-download browsers:
  docker compose build --no-cache
  docker compose up -d
  
• Fix (NPM):
  npx playwright install chromium
  

• Cause: The browser crashed, usually due to insufficient memory or shared memory limits.
• Fix:
  • Increase Docker memory limits in docker-compose.yml:
    deploy:
      resources:
        limits:
          memory: 2g
    shm_size: '1g'
    
  • Figranium already passes --disable-dev-shm-usage by default, which helps on constrained systems.

• Cause: The host machine is out of RAM.
• Fix: Restart Docker, increase swap space, or upgrade your instance.

​

2. Proxies not working

• 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.

​

3. Element not found

• 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_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).

​

4. Figranium 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:
    SESSION_SECRET=your-long-random-secret-here
    
• 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.

​

5. CAPTCHA / Bot Detection

• Cause: The target website detected automated browser behavior.
• Fix:
  1. Enable Stealth Mode options in the Task Editor (natural typing, idle movements, etc.).
  2. Use high-quality Residential Proxies rather than datacenter IPs.
  3. Rotate User Agents in Settings > System > User Agent.
  4. Add random wait actions (500–2000ms) between interactions.
  5. Avoid actions that no human would do (instant form fill, no mouse movement).

​

6. 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.

​

7. Data extraction returns empty or wrong results

• Cause 1: The extraction script runs before dynamic content finishes loading.
  • Fix: Add wait or wait_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.

​

8. 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 condition to break the loop.
• Cause 2: A wait_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.

​

9. 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.

​

10. 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.

​

11. API key save returns 400 (API_KEY_TOO_LONG)

• Cause: The API key you provided exceeds the 512-character limit. This applies to the system API key and all AI provider keys (Gemini, Claude).
• Fix: Use a shorter key. Standard provider keys are well under this limit — if you hit it, check for accidental whitespace or extra characters in your input.

​

Getting More Help

• Check the execution logs in the Executions tab for detailed error messages.
• Use the Headful Browser to observe your task running in real time.
• File issues at the Figranium GitHub repository.