# session token expired mid accessibility audit run failed - how to fix it

## TL;DR

Refresh the session before it dies: the agent should check the session expiry before each batch of pages and refresh proactively, and on a 401 mid-run it should refresh once and retry the failed page rather than aborting. One line of why: authenticated audits run long, sessions expire mid-run by design, and aborting wastes everything crawled so far.

## The error, verbatim

```text
AuditAgentError: session expired mid-audit (401 on /admin/users)
    crawled: 210/500 urls, auth: session cookie, refreshed: never

```

## Fix it step by step

### Step 1: Reproduce the 401

```bash
node agent/crawl.js --auth | rg -i '401|session|expired' | head -5
```

Expected: The 401 hits partway through the authenticated crawl.

### Step 2: Check the session lifetime

```bash
node -e "console.log('session ttl: 30m, crawl time: 2h, refresh: none')"
```

Expected: The math guarantees expiry mid-run.

### Step 3: Add proactive refresh

```bash
rg -n 'auth|refresh|401' agent/crawl.js | head -10
```

Expected: Add: refresh when under 5 minutes of life remain, retry once on 401 after refresh.

### Step 4: Re-run the audit

```bash
node agent/crawl.js --auth | tail -4
```

Expected: Agent refreshes mid-run and completes all 500 URLs.

### Step 5: Add a regression probe

```bash
node agent/run-audit.js --smoke | tail -3
```

Expected: Smoke run passes; schedule it so the breakdown is caught if it ever regresses.

## When to use this skill

- You run an agent that scans UIs for accessibility and it hits this breakdown
- The agent's scan loop stalls, crashes, or loops on this exact failure
- You are hardening an audit agent's error handling for production scans

## When NOT to use this skill

- A human runs the scan manually and it works, this is agent-harness failure handling
- The scan completes and only reports violations, use the rule-specific skills

## Compatibility

Audit agent with session auth. Refresh logic depends on the app's session endpoint. Pin the tool version in the lockfile so scans stay reproducible across machines.

## Variant phrasings

### agent auth expired mid crawl

Same failure, same refresh logic.

### 401 mid accessibility audit

Practitioner phrasing.

### the breakdown hits other routes too

Agent failure modes are systemic; apply the hardening to every route the agent covers, not just the one that failed.

## Why it happens

Authenticated audits need sessions, sessions expire, and long crawls outlast them. Agents that authenticate once at startup die with a 401 halfway through. The fix is proactive: track the session expiry, refresh before starting each batch when little life remains, and treat a mid-run 401 as refresh-and-retry-once, not abort. Persist the crawl frontier too, so even a failed refresh does not lose progress. Agent breakdowns are systemic: the same failure mode will hit every route, page, or run the agent touches. Harden the harness once (timeouts, loop detection, verification gates) instead of patching per page, and keep breakdown telemetry separate from violation counts.

## Edge cases

- Never log session tokens, the agent's logs should show expiry times, not token values.
- Some apps invalidate sessions on concurrent use, keep one authenticated agent session at a time.
- If refresh requires interactive login, the agent needs a stored refresh mechanism or the run must be attended.
- Log breakdowns separately from violations in agent telemetry; mixing them hides whether the agent itself is getting more reliable.

## Provenance

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