# Fix onboarding agent stuck when headless login fails after session cookie expires

## TL;DR
The login fails because the agent reuses a stale session cookie instead of logging in fresh. Detect the expired session, clear the cookie, and run the full login flow again. Stale sessions are not logins.

## The error
```text
Browser automation failed
Headless login failed after session cookie expired. Onboarding agent stuck.
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=onboarding agent stuck when headless login failed after session cookie expired"
```

## Fix it

### Step 1: Detect the expired session

```bash
Check for the login page or an auth redirect instead of assuming the session is valid.
```

Expected: The agent knows the session is dead.

### Step 2: Clear the stale cookies

```bash
Wipe the browser context's cookies for the site.
```

Expected: No stale state lingers.

### Step 3: Run the full login flow

```bash
Execute the complete login with fresh credentials.
```

Expected: A new valid session is established.

### Step 4: Validate the session before work

```bash
After login, confirm an authenticated state before proceeding.
```

Expected: The agent never works on a dead session.

### Step 5: Verify onboarding completes

```bash
Run the full onboarding flow.
```

Expected: It finishes without session stalls.

## When this applies

- Agents stall on expired session cookies
- Headless logins fail intermittently
- You are building long-running browser agents

## When it doesn't

- The credentials are wrong (fix those)
- The login page changed (fix the selectors)
- Sessions expire mid-run constantly (shorten the run or refresh)

## Compatibility

Headless browsers: Playwright, Puppeteer. Cookie-based sessions.

## Variant phrasings

### headless login session expired

Same stall. Detect, clear, and re-login.

### agent stuck expired cookie login

Stuck means the agent never noticed the expiry. Check session validity explicitly.

### browser session cookie expired automation

Cookies expire on the site's schedule, not yours. Plan for it.

## Why it happens

Session cookies have lifetimes, and agents that assume a persistent login break when the cookie dies. The agent keeps acting as if authenticated, every action fails or redirects, and it stalls. Explicit session validation plus re-login handles the lifecycle.

## Edge cases

- Some sites expire sessions aggressively on IP or fingerprint change; headed mode can help
- Storing session cookies across runs needs secure handling
- Refresh endpoints beat full re-logins where the site offers them

## If it still fails

- Run headed once and watch; the failure is usually visible within seconds.
- Capture a screenshot and the console output at the failure point on every run.
- Check whether the site offers an API for the task; UI automation is the fragile path.
- Test with a fresh browser profile to rule out cookie or cache state.
- If the site added bot protection, stop and use the sanctioned path. Do not work around it.

## Prevention

- Prefer APIs over browser automation wherever the site offers one.
- Screenshot on every failure so flakes are diagnosable.
- Use resilient selectors and re-validate them on a schedule.
- Keep automation accounts' sessions and auth factors maintained.
- Rate-limit automation traffic so it never looks like an attack.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_NzhHBp-jCsLc9A3CWWZO7A