Error Handling

Default Behavior

By default, if an action fails the task keeps running. The failed action is skipped and the next one executes.

To change this, set config.continueOnError: false — the task will stop at the first failure.

Stop on First Error

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

With config:

{
	"actions": [...],
	"config": { "continueOnError": false }
}

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

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

Field	Description
actionIndex	Position of the action that failed (starts at 0)
error	What went wrong

Per-Action Override

You can override the global setting for a single action using options.continueOnError.

This is useful when one step is optional — let it fail silently while everything else still stops on error:

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

The popup click can fail without stopping the task. All other actions will stop on error.

Common Errors

Error	Cause	Fix
Element "selector" not found within Xms	Element doesn't exist or hasn't loaded yet	Increase timeout, check the selector, or add waitForElement before it
Element is not a SELECT element	Used selectOption on the wrong element	Make sure the selector targets a <select> element
Iframe not found	The iframe option selector doesn't match	Check the iframe selector
Task timed out	Worker didn't finish in time	Increase the task timeout
Worker is offline	Extension disconnected	Check the extension is running and connected
No available workers	All workers are busy or offline	Wait and retry, or connect more workers
Daily task limit reached	Free plan: 50 tasks/day	Upgrade your plan or wait until tomorrow

Timeout Tips

Increase timeout for a slow element:

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

Wait for network activity to finish after navigation:

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

Add a short wait before checking for an element on a slow page:

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

HTTP Error Codes

Code	Meaning
400	Bad request — invalid actions or missing fields
401	Invalid or missing bearer token
403	Feature not available on your plan
408	Task timed out
409	Worker busy, offline, or session mismatch
429	Daily task limit reached