# Troubleshooting

## Common Issues

### Agent Not Taking Screenshots

**Symptoms:** Review iterations complete but no screenshots appear in `review-screenshots/`.

**Diagnosis:**
1. Check that `agent-browser` is installed: `which agent-browser`
2. Check that the dev server is running: `lsof -iTCP:<port> -sTCP:LISTEN`
3. Check the log for "Dev server detected" vs "Dev server NOT detected"
4. Check that credentials are loaded: look for "Test credentials loaded" in the log

**Fixes:**
- Ensure `.autobuilder/.env` has `PORT`, `TEST_USERNAME`, `TEST_PASSWORD`
- Make sure the dev server is running before starting the daemon, or use an `on-start` hook to start it
- Check that the port in config matches the actual dev server port

### Screenshots Saving to /tmp Instead of Initiative Directory

**Cause:** The prompt didn't include the screenshot directory path.

**Fix:** This was fixed by passing `screenshot_dir` explicitly to the prompt builder. If you're on an older version, update to the latest code.

### Agent Can't Get Past Login Page

**Symptoms:** Screenshots show only the login page. Agent mentions "SSO redirect" or "cookie issues".

**Fixes:**
- Add `TEST_USERNAME` and `TEST_PASSWORD` to `.autobuilder/.env`
- If the app uses SSO/OAuth, you may need a direct login endpoint or test account that bypasses SSO
- Check if the app has a different login flow for test environments

### Port Conflicts Between Projects

**Symptoms:** Screenshots show content from the wrong project.

**Diagnosis:**
```bash
lsof -iTCP:3000 -sTCP:LISTEN
lsof -iTCP:3100 -sTCP:LISTEN
```

**Fix:** Ensure every project has a unique port in `config.json` and `.autobuilder/.env`. Kill stale dev servers:
```bash
lsof -t -i:3000 | xargs kill
```

### Daemon Exits Immediately

**Check:**
1. Is there a `.autobuilder/stop` file? Delete it.
2. Is there an active initiative? Check `.autobuilder/active-initiative`.
3. Does the initiative have a `spec.md`? Check `.autobuilder/initiatives/<active>/spec.md`.

### Agent Keeps Failing (Consecutive Failures)

**Symptoms:** Log shows repeated "Agent failed" messages with increasing backoff.

**Diagnosis:**
1. Check if `cursor` / `codex` CLI is available: `which cursor`
2. Check if the model is accessible (API key, rate limits)
3. Check if the prompt is too large (very large specs can exceed context window)

**Fix:** The daemon automatically recovers after up to 5 consecutive failures. If it doesn't recover:
- Check your API credentials
- Try a different model with `--model`
- Reduce the size of `spec.md` or `constraints.md`

### Review Phase Always Runs (Never Skips to Execute)

**Cause:** The review phase creates new tasks every iteration, so there are always unplanned tasks that trigger `plan → execute`.

**This is normal behavior.** The review is designed to continuously find improvements. To reduce review frequency, you could:
- Reduce the strategy pool to fewer strategies
- Lower task limits to reduce output

### Config Changes Not Taking Effect

**Cause:** Unlikely — config is loaded every iteration. But check:
1. Config file syntax is valid (no tabs, proper indentation)
2. The key name matches exactly (use underscores, not hyphens, for values; hyphens are OK for top-level keys)
3. The daemon is actually running (check PID file)

### Journal.jsonl Growing Too Large

The journal file grows by one line per iteration. At ~200 bytes per entry, 1000 iterations = ~200KB. The daemon only reads the last 80 entries for strategy selection, so the file size doesn't affect performance.

To trim manually:
```bash
tail -500 .autobuilder/journal.jsonl > /tmp/journal-trimmed.jsonl
mv /tmp/journal-trimmed.jsonl .autobuilder/journal.jsonl
```

## Log Analysis

### Key Log Lines

```bash
# What phases ran
rg "Phases:" .autobuilder/loop.log

# What strategy was used
rg "Strategy:" .autobuilder/loop.log

# Whether dev server was detected
rg "Dev server" .autobuilder/loop.log

# Whether credentials were loaded
rg "credentials" .autobuilder/loop.log

# Agent exit codes
rg "rc=" .autobuilder/loop.log

# Tasks created
rg "Created tasks:" .autobuilder/loop.log

# Tasks executed
rg "Executed tasks:" .autobuilder/loop.log
```

### Checking Agent Output

The daemon streams agent output to the log. To see what the agent said in a specific iteration:

```bash
# Find iteration boundaries
rg "═══ Iteration" .autobuilder/loop.log
```

Note: `cursor agent --print` only streams the agent's natural-language summary, not underlying tool calls. If you need to see tool calls, check the Cursor IDE's agent history.

## Environment Requirements

| Requirement | Check | Fix |
|---|---|---|
| Python 3.8+ | `python3 --version` | Install Python |
| Cursor CLI | `which cursor` | Install Cursor |
| Git | `which git` | Install Git |
| `gh` CLI | `which gh` | `brew install gh` |
| `agent-browser` | `which agent-browser` | Install from npm |
| Node.js (for dev servers) | `which node` | Install Node.js |
