# Fix agent screenshot tool failing when the onboarding agent times out on a cookie wall

## TL;DR
The screenshot tool fails because the page never gets past the cookie wall and the agent's wait times out first. Dismiss or accept the cookie banner before screenshotting, and scope the wait to the banner, not the whole page. The tool is fine; the page is gated.

## The error
```text
Agent failed
Screenshot tool failed: timed out waiting on cookie wall. No screenshot captured.
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=agent screenshot tool failed when onboarding agent timed out on cookie wall"
```

## Fix it

### Step 1: Detect the cookie banner

```bash
Have the agent look for common cookie banner selectors before doing anything else.
```

Expected: The banner is found or confirmed absent.

### Step 2: Accept or dismiss it

```bash
Click the accept or reject button per your policy.
```

Expected: The banner clears and the page becomes interactive.

### Step 3: Scope waits to page readiness

```bash
Wait for the banner to clear and the main content to load, not a fixed long sleep.
```

Expected: Waits end as soon as the page is usable.

### Step 4: Retry the screenshot

```bash
Capture the screenshot again after the banner is gone.
```

Expected: The screenshot captures the real page.

### Step 5: Make banner handling standard

```bash
Add cookie-wall handling to the agent's default page-load routine.
```

Expected: Future pages never stall on banners.

## When this applies

- Screenshot tools time out on cookie walls
- Onboarding screenshots come back blank or partial
- You are building browser agents for onboarding

## When it doesn't

- The page never loads at all (check the URL and network)
- Screenshots fail with no banner present (check the tool)
- The banner cannot be dismissed (check the site's behavior)

## Compatibility

Browser automation screenshots: Playwright, Puppeteer, and similar.

## Variant phrasings

### screenshot timeout cookie banner agent

Same failure. Banner handling before capture fixes it.

### agent stuck on cookie wall screenshot

Stuck means the wait never ends. Scope the wait to the banner.

### cookie consent blocking agent screenshot

Consent walls gate everything behind them. Handle them first, always.

## Why it happens

Cookie walls overlay the page and block interaction until dismissed. Agents that wait for general page readiness, or sleep fixed durations, time out behind the wall and the screenshot tool reports the timeout. Handling the banner explicitly unblocks the whole flow.

## Edge cases

- Banner designs vary wildly; keep a list of selectors and update it
- Some regions require reject-first handling; match the site's legal posture
- Headless browsers sometimes render banners differently; test in the real mode you ship

## If it still fails

- Reproduce with a minimal run: one user, one file, one step.
- Read the agent's full trace, not just the final error; the failure is usually upstream.
- Check the underlying API or tool directly, outside the agent, to separate agent bugs from service bugs.
- Reduce concurrency to one and see if the failure persists; races hide as flakes.
- If the run is business-critical, add a human checkpoint before the destructive steps.

## Prevention

- Checkpoint long runs so any failure resumes instead of restarting.
- Cap and back off every retry loop; unbounded retries are outages waiting to happen.
- Validate inputs at each pipeline stage; fail fast with clear errors.
- Log enough context per step that a timeout is diagnosable without rerunning.
- Give destructive steps a human checkpoint or a dry-run mode.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_6AnhFwPM75jare8LpmjH4w