Error Handling

Retry mechanism

The SDK has built-in retry support. When script() throws an error, the SDK will automatically retry the entire profile (open browser → run script → close browser).

Configure via execution params:


const params = {
  execution: {
    concurrency: 3,
    maxRetries: 2,          // retry failed profiles up to 2 times
    keepOpenOnError: false,  // close browser on error (default)
  },
}

Log output during retry:


❌ Login failed — retrying in 2s...
🔄 Retrying... (1/2)

Example 1 — Auto retry


async script(context) {
  const browser = new BrowserUtils(context)
 
  await browser.goto(context.globalInput.targetUrl)
 
  // If this returns false → throw to trigger retry
  const loggedIn = await browser.exists('#dashboard', 15000)
  if (!loggedIn) throw new Error('Dashboard not found — will retry')
  // SDK will retry script() up to maxRetries times
}

Example 2 — Custom error handling (no retry)


async script(context) {
  const browser = new BrowserUtils(context)
 
  const ok = await browser.goto('https://example.com')
  if (!ok) {
    // Log error but don't throw — prevents retry
    await browser.writeOutput('loginStatus', 'Navigation failed')
    await browser.screenshot('error.png')
    return // exit gracefully
  }
 
  await browser.writeOutput('loginStatus', 'Success')
}

`keepOpenOnError`

When true, the browser window stays open after an error — useful for debugging.

Log output: ⚠️ Keeping browser open for debug (keepOpenOnError=true).

Example 1 — Debug mode


const params = {
  execution: {
    concurrency: 1,
    keepOpenOnError: true,  // browser stays open for inspection
  },
}

Example 2 — Production mode


const params = {
  execution: {
    concurrency: 5,
    keepOpenOnError: false,  // close immediately to free resources
    maxRetries: 3,
  },
}

Abort / Cancel

Flows can be cancelled externally (from the desktop app or agent). The SDK checks for abort signals before every action in BrowserUtils. When cancelled, it throws Error('cancelled') which is not retried.

Profile event: Stopped. (status: cancelled)

Best Practices

Check return values — click(), goto(), type() return boolean, use them instead of try/catch
Use exists() before click() — handle optional elements gracefully
Write output before throwing — ensures partial results are saved
Use screenshots for debugging — browser.screenshot('step-name.png')
Set reasonable timeouts — don’t wait forever for elements