App Platform Troubleshooting

App Platform Troubleshooting Skill

Transform debugging from guessing to rapid diagnosis and fix.

Philosophy

Traditional: See error → Guess → Change → Push → Wait 5-7 min → Repeat
With skill:  See error → Diagnose → Fix → Verify → Commit proper fix

Quick Decision

Is the app deployed with running containers?
├── YES → Can we access the shell?
│         ├── YES → LIVE MODE (SDK shell access)
│         └── NO  → LOGS-ONLY MODE (fetch logs)
└── NO (build/deploy failed) → LOGS-ONLY MODE

---

Mode 1: Live Troubleshooting (Quick Start)

from do_app_sandbox import Sandbox

app = Sandbox.get_from_id(app_id="", component="web")

# Diagnostics
app.exec("env | grep DATABASE")
app.exec("curl -v localhost:8080/health")
app.exec("ps aux | head -10")

Full guide: See [live-troubleshooting.md](reference/live-troubleshooting.md)

---

Mode 2: Logs-Only (Quick Start)

# Runtime logs
doctl apps logs   --type run

# Build logs
doctl apps logs   --type build

# Crash logs
doctl apps logs  --type=run_restarted

Full guide: See [logs-analysis.md](reference/logs-analysis.md)

---

Debug Container (Infrastructure Issues)

Deploy in ~30-45 seconds to isolate infrastructure from application:

services:
  - name: debug
    image:
      registry_type: GHCR
      registry: ghcr.io
      repository: bikramkgupta/debug-python
      tag: latest
    http_port: 8080
    envs:
      - key: DATABASE_URL
        value: ${db.DATABASE_URL}

# Run validation suite
validate-infra all
validate-infra database
validate-infra kafka

Full guide: See [debug-container.md](reference/debug-container.md)

---

Quick Reference: Exit Codes

| Code | Signal | Meaning | |------|--------|---------| | 0 | - | Clean exit (shouldn't exit) | | 1 | - | General error | | 127 | - | Command not found | | 137 | SIGKILL | OOM killed | | 143 | SIGTERM | Graceful shutdown |

---

Quick Reference: Common Fixes

| Problem | Quick Fix | |---------|-----------| | App exits immediately | Check if listening on $PORT | | 502 errors | Check health endpoint, verify running | | Database connection fails | Use Debug Container, verify trusted sources | | Build fails | Check dependencies, review build logs | | OOM kills | Upgrade instance size | | Health checks fail | Bind to 0.0.0.0, not localhost | | Slow startup | Increase initialdelayseconds |

---

Reference Files

• [live-troubleshooting.md](reference/live-troubleshooting.md) — SDK shell access, diagnostics, hot fixes
• [logs-analysis.md](reference/logs-analysis.md) — Log patterns, error codes, health check config
• [debug-container.md](reference/debug-container.md) — Infrastructure validation, validation suite
• [networking-issues.md](reference/networking-issues.md) — DNS, CORS, VPC, routing
• [app-maintenance.md](reference/app-maintenance.md) — Archive/unarchive workflow
• [diagnostic-scripts.md](reference/diagnostic-scripts.md) — Scripts, testing strategy, performance

---

When to Escalate

Contact DigitalOcean Support when:

• Internal error persists after redeploy
• Resource limit increases needed
• Multiple apps affected (platform issue)
• VPC/networking issues can't be diagnosed

Before escalating, gather:

doctl apps get  -o json > app_info.json
doctl apps logs   --type run > runtime.log
doctl apps spec get  > app_spec.yaml

---

Integration with Other Skills

• → deployment: After fixing, deploy proper changes
• → devcontainers: Reproduce issues locally
• → postgres: Database-specific configuration
• → networking: Comprehensive networking docs

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: digitalocean-labs
• Source: digitalocean-labs/do-app-platform-skills
• License: MIT

Install and usage instructions live in the source repository linked above.