# Fix setup agent failing after losing session state on SAML redirect

## TL;DR
The agent loses its session because the SAML redirect round-trip drops its state, usually cookies or in-memory context. Persist the agent's working state before the redirect and restore it from the RelayState or a state store after. The redirect is normal; the amnesia is the bug.

## The error
```text
Setup agent failed
Lost session state on SAML redirect. Cannot continue setup after login.
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=setup agent failed after losing session state on saml redirect"
```

## Fix it

### Step 1: Persist state before the redirect

```bash
Write the agent's working state, current step, and collected data, to durable storage before starting login.
```

Expected: The state survives the redirect round-trip.

### Step 2: Pass a state key through the flow

```bash
Include a state identifier in RelayState or the login request that maps back to the stored state.
```

Expected: The returning request carries the key to its own state.

### Step 3: Restore state after login

```bash
On the callback, load the stored state by the key and resume the setup step.
```

Expected: The agent continues where it left off.

### Step 4: Expire stale state

```bash
Give stored states a TTL and clean up abandoned ones.
```

Expected: No unbounded state growth from half-finished logins.

### Step 5: Test the full redirect cycle

```bash
Run setup through a real SAML login.
```

Expected: The agent resumes correctly after the redirect.

## When this applies

- Agents lose state across SAML login redirects
- Setup flows break right after SSO login
- You are building agents that drive browser SSO flows

## When it doesn't

- The SAML login itself fails (fix the SSO first)
- State is lost without any redirect (check the state store)
- The agent never had state to lose (different problem)

## Compatibility

SAML 2.0 redirects. Any agent driving browser-based SSO.

## Variant phrasings

### agent lost session saml redirect

Same failure. Durable state plus a key through the redirect fixes it.

### sso redirect killed agent state

Redirects reset browser contexts. Persist before, restore after.

### setup agent amnesia after login

Amnesia is always missing persistence. The redirect just exposes it.

## Why it happens

SAML login bounces through the browser to the IdP and back, and that round-trip resets whatever the agent held in memory or in redirect-sensitive cookies. Agents that keep all state in memory wake up after login with no idea what they were doing.

## Edge cases

- RelayState has size limits; store the bulk in your store and pass only a key
- Multiple concurrent logins need per-flow state keys, not one global slot
- SameSite cookie policies can drop session cookies on the cross-site bounce; test in the real browser

## 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_PTMKCsRS8h716J1nM8csVg