> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browserbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Captchas

> Keep your agent from interrupting CAPTCHA solving or handing off to a human before Browserbase finishes.

A CAPTCHA on the page doesn't mean your agent needs a human. Browserbase may already be solving it. If the agent clicks the challenge, reloads, or navigates away, it can interrupt that solve.

Listen for Browserbase's [CAPTCHA solving events](https://docs.browserbase.com/platform/identity/captcha-solving.md#captcha-solving-events), wait while the solver is working, and check the page before deciding whether to continue or escalate.

## Let Browserbase finish before continuing

Browserbase sends messages to the browser console as it works on a CAPTCHA. Your application can use those messages to tell whether the solver is working, has finished, or hit an error.

When solving starts, let Browserbase work without clicking, typing, reloading, or navigating away. Wait before asking a human to take over, too. For example, if your agent encounters a challenge during checkout, it should give the solver time to finish before asking someone to click the challenge.

When solving finishes, check that you can actually continue the task. Look for something concrete: the account dashboard after login, or the order confirmation after checkout. The solver finishing does not necessarily mean the site has granted access. If no challenge appears and the expected page is ready, continue normally.

[CAPTCHA solving](https://docs.browserbase.com/platform/identity/captcha-solving.md) can take up to 30 seconds depending on the challenge. Set an overall wait limit that allows time for the solve and the site's response. Keep it within your browser tool and session timeouts, and don't restart it each time another challenge appears.

## Listen for solver events

Register a console listener **before** the first navigation or action that could trigger a challenge. Keep listening throughout the task, including after clicks and form submissions. Track each page separately and attach listeners to new tabs before driving them.

| What happens | What to do |
| - | - |
| `browserbase-solving-started` | Wait without interacting with the page or handing control to a human. Keep listening until the solve finishes, errors, or reaches your wait limit. |
| `browserbase-solving-finished` | Check that the page or element you need is available. Continue only when it is ready and no solve is active. |
| `browserbase-solving-errored` | Record the failed attempt and keep watching for a new `started` event within the original deadline. The site may trigger another challenge after an error. |
| Deadline expires | Stop waiting and return a timeout with the session ID, last observed event, and whether a solve is active. Do not hand off an actively solving page. |
| No solve events | Continue if the expected page is ready. If it stays blocked, stop at your wait limit and investigate. |

If you build your own agent loop, put this behavior in the browser tool so the agent cannot skip the wait:

1. Subscribe to events before driving the page. Remember the latest solver status, including events that arrive before the tool starts waiting.
2. Before issuing an action, wait for any active solve to settle within your wait limit.
3. Execute one browser action. If it triggers a solve, wait before returning control to the agent for another action or handoff decision.
4. Check for the page or element you need while continuing to listen. If another challenge starts, wait again within the original time limit.
5. Tell the agent whether the page is ready or why the wait failed. Remove listeners when the page or task is finished.

See the [Playwright and Selenium event examples](https://docs.browserbase.com/platform/identity/captcha-solving.md#captcha-solving-events) for subscribing to the console. Those examples show event collection; your application must implement the waiting and readiness checks above. With Selenium, poll logs throughout the wait rather than reading them only once.

## Know when to ask for help

Recheck the page after solving finishes and allow time for the page or element you need to load, within your overall wait limit. An `errored` event ends an attempt, but the site may trigger another challenge. Keep the listener attached and watch for a new `started` event while checking the page, within the original overall wait limit. If another solve starts, keep waiting without restarting that deadline.

Ask for human help only when no solve is active and the page remains blocked after you have waited for the expected page or element. If the overall deadline expires while a solve is active, return a timeout with that state to your application instead of handing control to a human. If the result of a submission is uncertain, inspect it before retrying.

Include the session ID, affected page, last solver event and its timestamp, and what you expected to see on the page. Use [Session live view](https://docs.browserbase.com/platform/browser/observability/session-live-view.md) when your workflow needs a human to inspect the same session.

## Give your agent matching instructions

Once your browser tool handles the wait, use a prompt to explain the behavior to your agent. The tool must listen for events and share the solver status with the agent; a prompt alone cannot do that. Printing events to your application's terminal does not make them visible to the model.

> [accordion] Short prompt
>
> Add this instruction alongside your task prompt.
>
> ```text theme={null}
> When browserbase-solving-started appears, wait for
> browserbase-solving-finished before continuing. While solving, do not
> click, type, reload, navigate, or ask a human to solve the CAPTCHA.
> After finished, check that the expected page or element is accessible.
> If browserbase-solving-errored appears, keep watching for another
> started event within the original time limit. Ask for human help only
> when no solve is active and the page remains blocked after the readiness
> check. If the overall wait expires, report a timeout and the solver state.
> Follow https://docs.browserbase.com/optimizations/captcha-solving-for-agents.
> ```

> [accordion] Detailed prompt with timeout and recovery guidance
>
> Adapt this example to your tool names and wait limit. Its 60-second timeout is an example application budget, not a solve-time guarantee.
>
> ```text theme={null}
> CAPTCHA handling:
> - A visible CAPTCHA is not, by itself, a reason to request human help.
> - Read the solver status supplied by the browser tool. On
>   browserbase-solving-started, let Browserbase finish without interacting
>   with the page or handing control to a human.
> - Use the tool's bounded wait, configured here for 60 seconds. Do not
>   repeatedly call browser actions or restart the timeout while waiting.
> - On browserbase-solving-finished, inspect the page again and wait for
>   the task's expected element or destination. A finished event alone
>   does not prove that access succeeded.
> - If no challenge occurs and the expected page is ready, continue;
>   do not require a solve event on every page.
> - On browserbase-solving-errored, record the failed attempt and keep
>   watching for a new browserbase-solving-started within the original
>   deadline. The site may trigger another challenge. Do not hand off
>   immediately or reset the deadline.
> - Ask for human help only when no solve is active and the page remains
>   blocked after the bounded readiness check.
> - If the overall wait expires, return a timeout with the session ID,
>   last solver event, and whether a solve is still active. Do not hand
>   control to a human while the solver is working.
> - Do not repeat a payment, submission, or other action with side effects
>   without first checking whether it already succeeded.
> ```

## Troubleshoot missing events

* **Listener attached too late:** subscribing after `goto()` or a click can miss a fast solve. Subscribe first.
* **Events never reach the agent:** verify that your tool returns solver status or holds the action until the solve settles. A screenshot alone does not tell the agent whether Browserbase is working.
* **Wrong page or new tab:** listen on the page where the challenge occurs, not only the original tab.
* **Wait is too short:** check the browser tool's timeout as well as the agent's overall budget. A longer session timeout does not extend a shorter tool timeout.
* **Solving is disabled:** confirm the session did not set `browserSettings.solveCaptchas` to `false`.
* **Unsupported or undetected challenge:** no `started` event does not prove a listener bug. For custom image CAPTCHAs, see [custom selectors](https://docs.browserbase.com/platform/identity/captcha-solving.md#custom-captcha-solving). If the page stays blocked, return the session ID for investigation instead of waiting indefinitely.

If a session's logs show `browserbase-solving-finished` but your agent reports that it never arrived, inspect listener timing, page selection, and event forwarding before changing the prompt or increasing the timeout.

## Related guides

> [card] [CAPTCHA solving](https://docs.browserbase.com/platform/identity/captcha-solving.md)
>
> Configure CAPTCHA solving and subscribe to solver events.

> [card] [Session live view](https://docs.browserbase.com/platform/browser/observability/session-live-view.md)
>
> Let a human inspect a session when your workflow needs help.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.