> ## Documentation Index
> Fetch the complete documentation index at: https://atlas.rebuildingus.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Scout troubleshooting

> Fix common Scout setup, run, browser, search, sync, and worker issues.

Start with doctor:

```bash theme={null}
scout doctor
scout doctor --atlas-url https://atlas.rebuildingus.org
scout doctor --worker
```

## Scout Cannot Find A Model

Inspect the active model configuration:

```bash theme={null}
scout config show
```

Re-run model setup:

```bash theme={null}
scout config model
```

If you use LM Studio or Ollama, make sure the app or local server is running
before retrying the run.

## Search-Backed Discovery Fails

Check search status:

```bash theme={null}
scout search status
```

Reconnect search-backed discovery:

```bash theme={null}
scout search connect
```

Known URL runs and article-corpus recovery do not need a search key. Runs with
`--location` and `--issues` need search only when Scout must find new public
sources.

Scripts can pass `SEARCH_API_KEY` instead of saving a search key.

## Credential Storage Fails

Scout uses the operating system credential store for login tokens and stored
search keys. Configure macOS Keychain, Windows Credential Manager, or Linux
Secret Service, then retry the command.

Profile TOML is not a secret store. Do not put API keys, login tokens, or search
keys in `scout config` files. Use `scout login`, `scout search connect`, or an
environment variable in scripts.

## Structured Resource Rows Look Wrong

For headerless CSV, TSV, pipe-delimited text, or ZIP resources, pass column
names in source order:

```bash theme={null}
scout run \
  --structured-columns "id,name,role,organization,city,state,source_url" \
  https://example.gov/public-roster.zip
```

If the output has names in the wrong field or empty context, inspect the source
file's published data dictionary and rerun with the corrected column list.

## Counts Pass But Data Looks Outdated

Source-backed counts do not prove currentness. Check exact unique people and
source coverage first:

```bash theme={null}
scout entries stats \
  --require-type person \
  --min-source-backed 100000 \
  --min-unique-people 100000
```

Then inspect a random people sample:

```bash theme={null}
scout entries list \
  --type person \
  --random \
  --unique-names \
  --limit 100 \
  --format json
```

If source context points to an old filing, archive, historical roster, or stale
page, treat the entry as historical evidence. Re-run discovery against current
sources before using the data for outreach, reporting, or public claims.

## Browser Rendering Fails

Scout uses normal HTML fetching first. When a page looks useful but only exposes
content after JavaScript runs, Scout may try headless Chromium through
Playwright.

If the browser fallback is unavailable or too expensive for your computer, turn
it off:

```bash theme={null}
scout config set scraper.browser_fallback_enabled false
```

If Playwright is installed but Chromium is missing, install the browser binary:

```bash theme={null}
uvx --from playwright playwright install chromium
```

If JavaScript-heavy public pages are important for the run, leave it enabled and
keep the browser budget bounded:

```bash theme={null}
scout config set scraper.max_browser_renders_per_run 8
scout config set scraper.max_browser_concurrent 1
```

## Sync Fails

Check sync readiness for the Atlas environment you are targeting:

```bash theme={null}
scout doctor --atlas-url https://atlas.rebuildingus.org
```

If doctor says the saved login cannot create an Atlas upload token, log in
again for that environment or use `ATLAS_API_KEY` in scripts.

Check the current saved login:

```bash theme={null}
scout auth status
scout whoami
```

Log in again:

```bash theme={null}
scout login --atlas-url https://atlas.rebuildingus.org
```

For workspace sync, confirm the workspace id:

```bash theme={null}
scout sync RUN_ID --target workspace --workspace WORKSPACE_ID
```

## Local Data Looks Wrong

Find the local database:

```bash theme={null}
scout db path
```

List recent runs and pages:

```bash theme={null}
scout runs list
scout pages list --limit 20
```

Resetting the database deletes local runs, entries, and pages:

```bash theme={null}
scout db reset
```

Use reset only when you no longer need the local results.