Debug a Tentacle
Diagnose and resolve issues with a tentacle that isn’t working as expected.
Prerequisites
Section titled “Prerequisites”tntcCLI configured with MCP access- A deployed tentacle exhibiting issues
1. Check Health Status
Section titled “1. Check Health Status”tntc status my-tentacle --detailThis shows:
- Deployment readiness (replicas, conditions)
- Image and runtime class
- Pod status and recent events
- Health classification (Green/Amber/Red)
2. Read Logs
Section titled “2. Read Logs”tntc logs my-tentacle --tail 50Look for:
- Startup errors (missing modules, config issues)
- Runtime errors (network failures, auth errors, node crashes)
- Timeout messages
3. Trigger a Manual Run
Section titled “3. Trigger a Manual Run”tntc run my-tentacle --timeout 60sThe response includes execution results or error details.
4. Run Security Audit
Section titled “4. Run Security Audit”tntc audit my-tentacleChecks:
- RBAC — service account permissions
- NetworkPolicy — egress rules match contract
- PSA — Pod Security Admission labels
5. Check Health Endpoint
Section titled “5. Check Health Endpoint”If the tentacle is running but producing wrong results, query the detailed health endpoint via MCP:
The wf_health tool classifies tentacles as:
- Green — running, low error rate
- Amber — running but elevated error rate or last run failed
- Red — not running or very high error rate
6. Validate Locally
Section titled “6. Validate Locally”tntc validatetntc testtntc dev # test locally with hot-reloadVerification
Section titled “Verification”- Issue is identified in logs or health status
- Fix is applied and verified locally with
tntc test - Redeployment resolves the issue (
tntc deploy) tntc statusshows Green health
Failure Modes
Section titled “Failure Modes”| Symptom | Likely Cause | Resolution |
|---|---|---|
Pod CrashLoopBackOff | Node throws on startup | Check logs for the exception, fix node code |
connection refused to external API | NetworkPolicy blocking | Verify dependency in contract, check tntc audit |
403 Forbidden from API | Wrong or expired secret | Update .secrets.yaml, redeploy |
| Timeout errors | Slow external service | Increase config.timeout, add retries |
module not found | Import path error | Check node paths in workflow.yaml |
| Stale code after deploy | ConfigMap not updated | Force a rollout: undeploy and redeploy |
| Health shows Amber/Red | Recent errors | Check detailed health for lastError and errorRate |