# Dh Troubleshoot

> Systematic debugging for infrastructure issues. Use when user reports errors, app not working, 502/504 errors, certificate problems, DNS issues, or says "debug", "not working", "help", "broken", "error". Use when this capability is needed.

- Skill: `tomevault-io/dh-troubleshoot` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/dh-troubleshoot`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/dh-troubleshoot/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/dh-troubleshoot

---


# Dockhand Troubleshoot

Systematic debugging guide for infrastructure issues. Supports quick triage for common problems and deep diagnostic chains for complex issues.

## Quick Triage Mode

For common errors, run targeted diagnostics:

### HTTP 502/504 (Bad Gateway)
```
1. traefik_status → Check if router exists for domain
2. dokploy_app_status → Verify app is running
3. ssh_exec "docker logs <container> --tail 50" → Check app logs
```
**Common fixes:**
- Container crashed → `dokploy_redeploy`
- Wrong port → Update Traefik config
- App startup failure → Check env vars

### Certificate Errors (HTTPS)
```
1. traefik_check_certs domain="<domain>" → Check cert status
2. dns_get_record name="<domain>" → Verify DNS points to Traefik
3. ssh_exec "docker logs traefik --tail 100 | grep acme" → ACME logs
```
**Common fixes:**
- DNS not propagated → Wait, check `dns_check_propagation`
- Rate limited → Wait 1 hour, use staging CA
- Wrong challenge type → Verify HTTP-01 port 80 open

### Cloudflare 521 (Origin Down)
```
1. ssh_exec "curl -I localhost:<port>" on platform-core → Test local
2. traefik_status → Verify Traefik running
3. ssh_exec "docker ps | grep traefik" → Container status
```
**Common fixes:**
- Traefik not running → Restart via Dokploy
- Firewall blocking → Check Hetzner firewall rules
- Network misconfiguration → Verify dokploy-network

### App Not Starting
```
1. dokploy_app_status → Get deployment status
2. ssh_exec "docker logs <container> --tail 100" → Startup logs
3. ssh_exec "docker inspect <container>" → Check config
```
**Common fixes:**
- Missing env var → Add via Dokploy UI
- Volume permission → Fix ownership
- Resource exhaustion → Check `check_resource_thresholds`

## Deep Diagnostic Chain

For complex issues, run full diagnostic sequence:

### Step 1: Infrastructure Health
```
check_resource_thresholds → All hosts CPU/memory/disk
monitoring_health → Prometheus/Grafana/Loki status
```

### Step 2: Edge Layer (Traefik)
```
traefik_status → All routers and services
traefik_check_certs → All certificate status
ssh_exec "docker logs traefik --tail 200" → Recent logs
```

### Step 3: Orchestration Layer (Dokploy)
```
dokploy_list_apps → All managed applications
dokploy_app_status app_id=<id> → Specific app details
```

### Step 4: Container Layer (Docker)
```
docker_state host="<host>" → Full container inventory
ssh_exec "docker ps -a" → Include stopped containers
ssh_exec "docker logs <container>" → Application logs
```

### Step 5: Network Layer
```
ssh_exec "docker network ls" → Network inventory
ssh_exec "docker network inspect dokploy-network" → Connectivity
dns_list_records → DNS configuration
dns_check_propagation domain="<domain>" → External resolution
```

### Step 6: Application Layer
```
ssh_exec "curl -I http://localhost:<port>" → Local health
ssh_exec "curl -I https://<domain>" → External health
```

## Diagnostic Output Format

Present findings in structured format:

```
=== Troubleshooting Report ===
Issue: <user-reported problem>
Timestamp: <when started>

## Quick Checks
- [ ] Host connectivity: OK
- [ ] Traefik status: OK
- [ ] App status: FAILED - container restarting
- [ ] DNS resolution: OK
- [ ] Certificate: OK

## Root Cause
Container `ghost` in restart loop due to missing DATABASE_URL

## Recommended Fix
1. Add DATABASE_URL to Dokploy environment variables
2. Redeploy application
3. Verify health post-deploy

## Commands to Execute
dokploy_redeploy app_id="xxx" confirmed=true
```

## Escalation Path

If quick triage doesn't resolve:
1. Run full diagnostic chain
2. Check Grafana dashboards for historical data
3. Review Loki logs for patterns
4. Check recent changes (git log, Dokploy activity)
5. Escalate to manual SSH investigation

## Integration with dh-deploy-validator

After fixing issues, trigger `dh-deploy-validator` agent to confirm resolution and prevent regression.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/masonjames) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->