Debug Failed Deployment
Run the full debug-deploy workflow against an application or compose stack — locate the failed run, read build logs, inspect container state, check Traefik, optionally AI-summarise, and recover.
Arguments
Format: [app-name-or-id|compose-id] (optional)
- If a UUID is passed, treat it as either an
applicationId or composeId and disambiguate by calling application-one first, falling back to compose-one.
- If a name is passed, call
project-all to resolve.
- If no argument is passed, call
mcp__plugin_dokploy-dev_dokploy__deployment-allCentralized and mcp__plugin_dokploy-dev_dokploy__deployment-queueList, list the recent error / stuck deployments, and ask the user which to investigate.
Parse from "$ARGUMENTS".
Process
Read ${CLAUDE_PLUGIN_ROOT}/skills/debug-deploy/SKILL.md and follow every step in order. Do not skip.
Key checkpoints:
- Step 0 — Platform health. Run
settings-health, checkInfrastructureHealth (returns postgres / traefik status), getDockerDiskUsage, and on v0.30+ the read-only host check docker-getServerHealth (disk, memory, inotify, network IP pools, daemon errors) plus docker-getEvents { minutes } for recent daemon activity. If any fail, fix server before deploy issue.
- Step 1 — Locate the failed run. Use
deployment-all filtered by the resource ID. Save deploymentId.
- Step 2 — Read the logs (Dokploy v0.29.0+ — runtime logs are first-class over MCP/REST/CLI; see the
read-logs skill). Build failure → deployment-readLogs { deploymentId, tail }. Runtime crash → application-readLogs { applicationId, tail, since, search } for an app, or read every container of a compose stack: docker-getContainersByAppNameMatch { appName, appType: "docker-compose" } then compose-readLogs { composeId, containerId, tail, since, search } per container (or /dokploy-dev:compose-logs). Match against the build-failure pattern table.
- Step 3 — Container introspection.
docker-getContainersByAppLabel { appName, type: "standalone" } for state/health. docker-getConfig for command/mounts/networks (its Env is [REDACTED] by default since @dokploy/mcp 0.30.0 — diagnose env problems from the logs, see the debug-deploy skill "Env and credentials"). Use docker-restartContainer / killContainer if wedged.
- Step 4 — Request path. Only if container is running but HTTP requests fail.
application-readTraefikConfig, check port, network, listen address.
- Step 5 — Recovery. Use the smallest action that unblocks:
killBuild / cancelDeployment / cleanQueues / deployment-removeDeployment / rollback-rollback. Confirm destructive ops with the user.
- Step 6 — AI summary. If
ai-getEnabledProviders is non-empty, pass the log text from Step 2 to ai-analyzeLogs { aiId, logs, context: "build" | "runtime" } and present the result. Otherwise note that AI is not configured and continue manually.
- Step 7 — Verify the fix. After applying a fix,
application-redeploy (or compose-redeploy), poll deployment-all until status: done, validate domains, hit the endpoint with curl.
Output format
Report findings in this structure:
## Diagnosis: <appName / composeName>
**Failed deployment:** <deploymentId> (status: error, started: <timestamp>)
**Build log:** <logPath>
### Root cause
<one-paragraph plain-language explanation>
### Evidence
- <log excerpt 1>
- <container state observation>
- <traefik / domain observation if relevant>
### AI summary (if available)
<ai-analyzeLogs output, condensed>
### Recommended fix
<concrete action, with the exact MCP call(s) needed>
### Recovery commands
<list of MCP calls to apply the fix and redeploy>
After applying a fix, re-verify before declaring the issue resolved.
Example Usage
/dokploy-dev:debug
/dokploy-dev:debug web-frontend
/dokploy-dev:debug abc123-def456
1---2name: debug3description: 'Debug a failed or stuck Dokploy deployment with full decision-tree analysis Arguments: app-name-or-id|compose-id.'4metadata:5 source: https://skillmd.com/skills/agents-store/debug6---78# Debug Failed Deployment910Run the full `debug-deploy` workflow against an application or compose stack — locate the failed run, read build logs, inspect container state, check Traefik, optionally AI-summarise, and recover.1112## Arguments1314Format: `[app-name-or-id|compose-id]` (optional)1516- If a UUID is passed, treat it as either an `applicationId` or `composeId` and disambiguate by calling `application-one` first, falling back to `compose-one`.17- If a name is passed, call `project-all` to resolve.18- If **no argument** is passed, call `mcp__plugin_dokploy-dev_dokploy__deployment-allCentralized` and `mcp__plugin_dokploy-dev_dokploy__deployment-queueList`, list the recent `error` / stuck deployments, and ask the user which to investigate.1920Parse from "$ARGUMENTS".2122## Process2324Read `${CLAUDE_PLUGIN_ROOT}/skills/debug-deploy/SKILL.md` and follow every step in order. Do not skip.2526Key checkpoints:27281. **Step 0 — Platform health.** Run `settings-health`, `checkInfrastructureHealth` (returns `postgres` / `traefik` status), `getDockerDiskUsage`, and on v0.30+ the read-only host check `docker-getServerHealth` (disk, memory, inotify, network IP pools, daemon errors) plus `docker-getEvents { minutes }` for recent daemon activity. If any fail, fix server before deploy issue.292. **Step 1 — Locate the failed run.** Use `deployment-all` filtered by the resource ID. Save `deploymentId`.303. **Step 2 — Read the logs (Dokploy v0.29.0+ — runtime logs are first-class over MCP/REST/CLI; see the `read-logs` skill).** Build failure → `deployment-readLogs { deploymentId, tail }`. Runtime crash → `application-readLogs { applicationId, tail, since, search }` for an app, or **read every container** of a compose stack: `docker-getContainersByAppNameMatch { appName, appType: "docker-compose" }` then `compose-readLogs { composeId, containerId, tail, since, search }` per container (or `/dokploy-dev:compose-logs`). Match against the build-failure pattern table.314. **Step 3 — Container introspection.** `docker-getContainersByAppLabel { appName, type: "standalone" }` for state/health. `docker-getConfig` for command/mounts/networks (its `Env` is `[REDACTED]` by default since `@dokploy/mcp` 0.30.0 — diagnose env problems from the logs, see the `debug-deploy` skill "Env and credentials"). Use `docker-restartContainer` / `killContainer` if wedged.325. **Step 4 — Request path.** Only if container is running but HTTP requests fail. `application-readTraefikConfig`, check port, network, listen address.336. **Step 5 — Recovery.** Use the smallest action that unblocks: `killBuild` / `cancelDeployment` / `cleanQueues` / `deployment-removeDeployment` / `rollback-rollback`. Confirm destructive ops with the user.347. **Step 6 — AI summary.** If `ai-getEnabledProviders` is non-empty, pass the log text from Step 2 to `ai-analyzeLogs { aiId, logs, context: "build" | "runtime" }` and present the result. Otherwise note that AI is not configured and continue manually.358. **Step 7 — Verify the fix.** After applying a fix, `application-redeploy` (or `compose-redeploy`), poll `deployment-all` until `status: done`, validate domains, hit the endpoint with curl.3637## Output format3839Report findings in this structure:4041```42## Diagnosis: <appName / composeName>4344**Failed deployment:** <deploymentId> (status: error, started: <timestamp>)45**Build log:** <logPath>4647### Root cause48<one-paragraph plain-language explanation>4950### Evidence51- <log excerpt 1>52- <container state observation>53- <traefik / domain observation if relevant>5455### AI summary (if available)56<ai-analyzeLogs output, condensed>5758### Recommended fix59<concrete action, with the exact MCP call(s) needed>6061### Recovery commands62<list of MCP calls to apply the fix and redeploy>63```6465After applying a fix, re-verify before declaring the issue resolved.6667## Example Usage6869```70/dokploy-dev:debug71/dokploy-dev:debug web-frontend72/dokploy-dev:debug abc123-def45673```