Troubleshoot Deploy

About

A comprehensive troubleshooting decision tree for deployment failures. Covers every stage of the pipeline (clone, build, push, deploy) with specific symptoms, causes, and fixes. Includes OAuth errors, database connection failures, DNS issues, and the correct read-only kubectl commands for debugging.

Skill Content

This is the raw markdown that gets installed as a Claude Code command.

# 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.

Install

Copy the skill content and save it to:

~/.claude/commands/troubleshoot-deploy.md

Details

Format

Command

Category

troubleshoot

Version

1.0.0

Tokens

~1,200

Updated

2026-02-13