Error Handling

How BrowserWorker handles action errors and how to control error behavior.

Default Behavior

By default, continueOnError is true — if an action fails, the task continues executing the remaining actions. The error is logged but doesn't stop the task.

Stop on First Error

Set config.continueOnError to false to stop execution immediately when any action fails:

{
  "actions": [
    { "openNewTab": "https://example.com" },
    { "click": ".must-exist-button" },
    { "screenshot": "viewport" }
  ],
  "config": {
    "continueOnError": false
  }
}

If .must-exist-button is not found, the task stops and returns an error:

{
  "success": false,
  "error": "Element '.must-exist-button' not found within 10000ms",
  "actionIndex": 1,
  "action": { "click": ".must-exist-button" }
}

Field	Description
actionIndex	Zero-based index of the action that failed
action	The action object that caused the error
error	Human-readable error message

Per-Action Override

Use options.continueOnError to override the global setting for a single action:

{
  "actions": [
    { "openNewTab": "https://example.com" },
    { "click": ".optional-popup", "options": { "continueOnError": true, "timeout": 2000 } },
    { "click": "#required-button" },
    { "screenshot": "viewport" }
  ],
  "config": {
    "continueOnError": false
  }
}

Here, the optional popup click can fail silently, but all other actions will stop on error.

Common Errors

Error	Cause	Solution
Element "selector" not found within Xms	Element doesn't exist or hasn't loaded yet	Increase timeout, check selector, add waitForElement
Element is not a SELECT element	Used selectOption on a non-select element	Verify the selector targets a <select>
Iframe not found	Iframe selector doesn't match	Check the iframe option selector
Task timed out	Worker didn't complete within timeout	Increase timeout, reduce actions
Worker offline	Extension disconnected	Check that the extension is running
No workers available	All workers busy or offline	Wait and retry, or register more workers
Daily task limit reached	Free plan: 50 tasks/day	Upgrade plan or wait until tomorrow

Timeout Strategies

Increase Per-Action Timeout

For slow-loading elements:

{
  "waitForElement": ".dynamic-content",
  "options": { "timeout": 30000 }
}

Use waitForEvent for Dynamic Pages

{
  "actions": [
    { "openNewTab": "https://spa-app.example.com" },
    { "waitForEvent": "networkIdle", "options": { "timeout": 15000 } },
    { "screenshot": "viewport" }
  ]
}

Give the Page Time to Load

{
  "actions": [
    { "openNewTab": "https://heavy-page.example.com" },
    { "wait": 3000 },
    { "waitForElement": "#main-content" },
    { "screenshot": "viewport" }
  ]
}

HTTP Error Codes

Code	Meaning	Action
400	Invalid request (bad actions format)	Fix your request JSON
401	Invalid bearer token	Check your token in the dashboard
403	Permission denied	Verify worker ownership or plan features
404	No available workers	Wait and retry
408	Task timed out	Increase timeout
409	Worker busy or session mismatch	Target a different worker or wait
429	Rate limit exceeded	Upgrade plan or wait