# Troubleshoot Deploy

## What this skill covers
Step-by-step diagnosis of Tawa deployment failures. Always check the build log first — it contains the most useful information.

## Step 1: Check build log

```bash
tawa status                         # get the latest build ID
tawa logs --build <build-id>        # read the full build log
```

**Look for these lines in the log:**

| Log line | Meaning | Fix |
|----------|---------|-----|
| `OAuth skipped (spec.auth not configured)` | No OAuth client provisioned | Add `spec.auth: mode: sso` to catalog-info.yaml |
| `⚠️ WARNING: OAuth credentials removed` | Had OAuth before, no longer | Add `spec.auth: mode: sso` to catalog-info.yaml |
| `OAuth client provisioned` | OAuth is working | No action needed |
| `Deploy gate: insufficient gas reserve` | Wallet too low | `tawa wallet buy <amount>` |
| `secret/...-managed-secrets unchanged` | No managed secret change | Normal — not an error |

## Step 2: Check pod status

```bash
tawa pods                           # pod states and restart counts
tawa logs                           # live container logs
tawa troubleshoot                   # AI-powered diagnosis
```

## Decision Tree

### Build fails at "building"
- **npm install fails** — check package.json for typos, verify packages exist on Forgejo registry
- **Node version mismatch** — set `insureco.io/node-version: "20"` in catalog-info.yaml annotations
- **TypeScript errors** — fix them locally first: `npm run build`

### Build fails at "deploying" — CrashLoopBackOff
1. Does `/health` (or `/api/health` for Next.js) return 200?
2. Is your app listening on port 3000?
3. Is a required env var undefined? Check `tawa logs` for startup errors
4. MongoDB connection failing on startup? Move DB connect after server starts listening

### Service deploys but login is broken
1. Check build log for `OAuth skipped` — if present, add `spec.auth: mode: sso`
2. Check build log for `OAuth client provisioned` — if missing and you need login, see above
3. Callback error "Invalid Redirect URI"? Must be at `/api/auth/callback` exactly
4. `BIO_CLIENT_ID is required` error? Same cause — missing `spec.auth: mode: sso`

### Service deploys but API calls return 401
1. Are routes declared in `catalog-info.yaml` with `auth: required`?
2. Are you passing a valid Bearer token in the Authorization header?
3. For Next.js: are you passing `request` to `getAuthUser(request)` in every API route?

### SMS / relay not working after deploy
- `RelayClient.fromEnv()` needs `BIO_CLIENT_ID` — check `spec.auth: mode: sso` is set
- Check `tawa logs` for `BIO_CLIENT_ID is required`

### Database connection fails
- **MONGODB_URI undefined** — add `databases: [{type: mongodb}]` to catalog-info.yaml
- **Connection refused** — first deploy? Builder provisions the DB, wait for deploy to finish

### DNS not resolving / site not accessible
- Wait 2-3 minutes after first deploy for Cloudflare propagation
- Verify `metadata.name` in catalog-info.yaml matches expected hostname

## Read-Only kubectl for Debugging

```bash
kubectl get pods -n {service}-{env}
kubectl logs -n {service}-{env} <pod-name>
kubectl logs -n {service}-{env} <pod-name> --previous   # for crash loops
kubectl describe pod -n {service}-{env} <pod-name>
```

**Never** use kubectl to write/apply/delete — use `tawa deploy` instead.

## Key Rule
Build log first. Then pod logs. Then `tawa troubleshoot` for AI diagnosis.
If the build log says `OAuth skipped`, that's catalog-info.yaml — not a code bug.