# Troubleshoot Deploy

## What this skill covers
A decision tree for diagnosing deployment failures on the Tawa platform.

## Quick Diagnostics

```bash
# Check pod status
tawa status

# View build logs
tawa logs --build <build-id>

# Stream live application logs
tawa logs

# AI-powered troubleshooter
tawa troubleshoot
```

## Decision Tree

### Build fails at "cloning"
- **Git remote not accessible** — Check `git remote -v`, ensure repo exists on GitHub or Forgejo
- **Private repo without token** — Forgejo repos need the Forgejo token configured in the builder
- **Branch doesn't exist** — Verify the branch name matches your current branch

### Build fails at "building"
- **Dockerfile syntax error** — Check auto-generated Dockerfile or your custom one
- **npm install fails** — Check package.json for typos, verify dependencies exist
- **Node version mismatch** — Set `insureco.io/node-version` annotation in catalog-info.yaml
- **Out of memory during build** — Large builds may need more memory; contact platform team

### Build fails at "pushing"
- **Registry auth error** — Builder registry credentials may be expired; check builder logs
- **Image too large** — Optimize your Dockerfile, use multi-stage builds, add .dockerignore

### Build fails at "deploying"
- **CrashLoopBackOff** — Pod starts but crashes immediately
  1. Check health endpoint: does `/health` or `/api/health` return 200?
  2. Check port: does your app listen on the port declared in catalog-info.yaml?
  3. Check logs: `kubectl logs -n {service}-{env} <pod>`
  4. Missing env var: app crashes because an expected env var is undefined

- **OOMKilled** — Pod exceeds memory limit
  1. Increase pod tier in catalog-info.yaml: `insureco.io/pod-tier: "small"`
  2. Check for memory leaks in your application

- **ImagePullBackOff** — Can't pull the Docker image
  1. Image push may have failed silently
  2. Check builder logs for push errors
  3. Verify the `insureco` imagePullSecret exists in the namespace

- **Deploy gate failure** — Insufficient wallet balance
  1. Check balance: `tawa wallet`
  2. Buy more tokens: `tawa wallet buy <amount>`
  3. Or reduce pod tier to lower the reserve requirement

### Service deploys but isn't accessible
- **DNS not ready** — Wait a few minutes for Cloudflare propagation
- **Wrong hostname** — Verify `metadata.name` in catalog-info.yaml matches expected URL
- **Ingress not configured** — Check that the Helm deploy included ingress settings
- **TLS certificate pending** — Cloudflare provisions certs automatically; wait 1-2 minutes

### OAuth errors after deploy
- **Invalid Redirect URI** — Your callback route must be `/api/auth/callback` exactly
- **client_id=undefined** — catalog-info.yaml may be missing; ensure it exists and builder is v1.2+
- **Unknown Application** — Bio-ID client wasn't created; check builder logs for OAuth provisioning errors
- **Token exchange fails** — Authorization codes expire after 60 seconds; check timing

### Database connection fails
- **MONGODB_URI undefined** — Database not declared in catalog-info.yaml
- **Connection refused** — Database host may be down; check with `tawa troubleshoot`
- **Authentication failed** — Shouldn't happen (no auth on platform DBs); check if URI is being modified

## Read-Only kubectl for Debugging

```bash
kubectl get pods -n {service}-{env}
kubectl logs -n {service}-{env} <pod-name>
kubectl describe pod -n {service}-{env} <pod-name>
kubectl port-forward -n {service}-{env} <pod-name> 3000:3000
```

## Key Rule
Always check `tawa status` and `tawa logs` first. Use `tawa troubleshoot` for AI-powered diagnostics. Only use kubectl for read-only debugging.