Logs & Monitoring

Stream live container logs, inspect builds, check pod status, and diagnose issues with AI-powered troubleshooting.

Pod Logs

Stream live container output from your running pods. By default, logs follow in real time (like tail -f) and show the last 100 lines.

# Stream logs from your service (run from project directory)
tawa logs

# Stream production logs (default is sandbox)
tawa logs --prod

# Stream UAT logs
tawa logs --uat

Flag	Description	Default
`--prod`	Show logs from production	sandbox
`--uat`	Show logs from UAT	sandbox
`--tail <n>`	Number of historical lines to show	100
`--no-follow`	Print logs and exit	follow=true
`--service <name>`	Target a different service	auto-detected

If your service has multiple replicas, the CLI color-codes each pod. JSON logs (e.g., via pino) are automatically parsed and formatted.

Build Logs

When a deploy is in progress or has completed, inspect the full build output:

# View logs for a specific build
tawa logs --build <build-id>

# Stream build logs in real-time
tawa logs --build <build-id> --follow

The build ID is printed when you run tawa deploy. You can also find it with tawa status.

Build stages

Stage	What happens
`queued`	Build accepted and waiting for a worker
`cloning`	Git clone from the linked repository
`building`	Docker image build
`pushing`	Pushes image to the container registry
`deploying`	Helm upgrade/install to Kubernetes + DNS configuration
`testing`	Deploy-gated smoke tests (if configured)
`completed`	Pods running, DNS active, service is live
`failed`	Something went wrong — check build logs for details

Status & Builds

# Show service info + recent builds
tawa status

# Show a specific build's details
tawa status --build <build-id>

# List recent builds (up to 10)
tawa builds

Troubleshooting

tawa troubleshoot

The AI-powered troubleshooter analyzes logs across all related services and suggests fixes.

Issue	Symptom	Typical Fix
Missing scopes	403 errors calling another service	`tawa scopes request`
Service not registered	404 from Janus gateway	Check `spec.routes` in catalog-info.yaml
Health check failure	Pod in CrashLoopBackOff	Ensure health endpoint returns 200
Out of memory	OOMKilled status	Increase `insureco.io/pod-tier` annotation
Database connection	ECONNREFUSED on startup	Check `spec.databases` config

Common Issues

"No pods found"

The service hasn't been deployed to that environment yet. Run tawa deploy (sandbox) or tawa deploy --prod (production).

Logs show nothing / pod is restarting

Your app is crashing on startup. Check:

Does your health endpoint respond with 200?
Are required environment variables set? (MONGODB_URI, etc.)
Run tawa logs --tail 200 to see the crash output

Build fails at "building" stage

The Docker build failed. Common causes:

npm install failed — check package.json for missing dependencies
npm run build failed — TypeScript errors in your code
Dockerfile copies a file that doesn't exist in the repo

Build succeeds but pod won't start

The image was built, but the container can't run:

Check tawa logs --prod for runtime errors
Ensure your app listens on the port specified (EXPOSE 3000)
nano tier gives 256MB, small gives 512MB

SSL certificate not ready

On the first deploy to a new subdomain, Cloudflare needs 1–3 minutes to provision the SSL certificate. Subsequent deploys are instant.

Last updated: February 28, 2026