# Avowex — troubleshooting

Find your symptom below. Most issues are one of three things: the API isn't
running, you're using the wrong key/base URL, or your plan gates the feature.

## Quick health checks

- API alive? open **http://localhost:8000/healthz** → `{"status":"ok"}`.
- Queue/throughput: **GET /v1/status**. Plan & usage: **GET /v1/plan**.
- Audit intact: **GET /v1/audit/verify** → `"intact": true`.

---

## Running the API (`start-local.bat`)

**"'python' is not recognized" / opens Microsoft Store**
Install Python 3.12 from python.org and tick **Add python.exe to PATH**, or use
`py` instead of `python`. Then re-run `start-local.bat`.

**"'docker' / 'make' is not recognized"**
You don't need them for local. `start-local.bat` runs on Python + SQLite only.
Docker is only for the production stack.

**Port 8000 already in use**
Something else is on the port. Close it, or run uvicorn on another port:
`uvicorn app.main:app --port 8001` (then use that base URL everywhere).

**Migration error / want a clean slate**
Delete `services/api/avowex.db` and re-run `start-local.bat` — it recreates the
database from scratch.

**Yellow `Invalid HTTP request received` warnings**
Harmless. Something hit the server over **https** — use **http://localhost:8000**.

**A new feature/endpoint 404s after an update**
Re-run `start-local.bat` so the new migration applies and the server restarts.

---

## The console / browser

**Dashboard or "Set up live" says "Could not load (network)"**
1. Is the API running? Open http://localhost:8000/healthz.
2. Is the **API** box set to `http://localhost:8000` (http, not https)?
3. Did you **restart** the API after the CORS change? (CORS lets the page call
   it from a file.) Stop with Ctrl+C and re-run `start-local.bat`.
4. Is the **Key** valid? Run "Set up live" to mint a fresh one.

**Buttons do nothing / "failed to fetch"**
Browser blocked the cross-origin call. Confirm the API is up and CORS is on
(it's enabled by default in dev via `CORS_ALLOW_ORIGINS=*`). Don't open the
console over `https://` while the API is `http://` — keep both http.

**Progress/checklist reset**
It's stored in your browser; a different browser/profile or cleared storage
starts fresh. Harmless.

---

## API responses (what the status code means)

- **401 Unauthorized** — missing/invalid/revoked key. Check the `Authorization:
  Bearer avx_...` header and that the key wasn't revoked.
- **402 Payment Required** — either you hit the **free monthly cap (500
  resolved)** or the feature needs a higher plan (Mode A, consensus, automation,
  domains, reporting, scoped keys, audit export, SSO/SCIM). Upgrade with
  `POST /v1/plan {"plan":"business"}` (or "enterprise"), or wait for the monthly
  reset.
- **403 Forbidden** — the key lacks the required **scope**, or a reviewer isn't
  **vetted**. Mint a key with the right scopes, or create the reviewer with
  `"vetted": true`.
- **404 Not Found** — unknown `action_type` (register it first), or an
  escalation that isn't owned by your org.
- **409 Conflict** — slug already taken, or a duplicate. For escalations a
  repeated `idempotency_key` is fine — fetch the existing one.
- **422 Unprocessable** — a bad field (invalid mode/strategy/plan/region, or a
  malformed slug). Check the error detail.
- **500** — server error. Look at the API terminal for the traceback.

---

## Behavior issues

**My escalation is stuck on `pending` forever**
Mode B escalations wait for a **reviewer** to resolve them. Either:
- resolve it from the **reviewer app** (`start-reviewer.bat`, paste an `avxr_`
  key), or via `POST /v1/escalations/{id}/decision` with a reviewer key, or
- let it **time out**: it auto-resolves to the policy fallback after
  `timeout_seconds`. The local sweeper runs every ~10s.
For Mode A, an **approver** must act on the signed token.

**Auto-resolution isn't happening (everything goes to humans)**
By design, until you (Business+) **train and promote** a resolver and set the
action type's `auto_resolve_threshold` below 1.0. Free plan can't train, so
everything routes to humans — that's expected.

**Reviewer gets 403 when voting**
The reviewer must be **vetted**. Create with `{"vetted": true}` (the default in
the SDK/console).

**Mode A / consensus / domains return 402**
Those are Business+ features. On Free, use **Mode B, single review**.

**SSO `GET /v1/auth/sso/authorize` returns 501**
Expected until WorkOS is configured. Set `WORKOS_API_KEY` and
`WORKOS_CLIENT_ID` in `.env`, restart, and the SSO flow activates.

**Notifications (Slack/SMS/email) don't fire**
They're no-ops until configured. Add the relevant keys to `.env`
(`SLACK_WEBHOOK_URL`, `TWILIO_*`, `SMTP_*`) and restart. Until then the API logs
that it skipped them — that's normal locally.

---

## Reviewer web app

**`npm`/`node` not recognized** — install Node.js 20+ (LTS) from nodejs.org.
**`npm install` fails the first time** — run it again (it resumes); ensure Node 20+.
**Queue shows sample data** — paste a reviewer key (`avxr_…`) at the top to load
the live queue; without one it shows demo data.

---

## Still stuck?

- Reset everything local: delete `services/api/avowex.db`, then `start-local.bat`.
- Re-run the automated checks: `test-stage4.bat` / `test-stage5.bat`.
- Read the API logs in the terminal — the traceback usually names the cause.