Debug Deploy

Debug a Failed Dokploy Deployment

This is the canonical workflow when a Dokploy deployment fails, gets stuck, or the production site does not change after a "successful" deploy. Work through the steps in order — each step narrows the cause and feeds the next.

Companion command: /dokploy-dev:debug [applicationId|composeId] runs this entire chain.

Reading logs (Dokploy v0.29.0+; current v0.29.14): Runtime and build logs are available directly over the REST API / MCP — no SSH or Beszel needed (the old issue #3719 gap is closed). There are two distinct artifacts: the build log (deployment-readLogs { deploymentId, tail }) explains why an image failed to build; the runtime log (application-readLogs / per-container compose-readLogs / {db}-readLogs, all with tail/since/search) explains why a running container is crashing. For a multi-container Compose stack you must enumerate the containers and read each one — see the read-logs skill, which this workflow uses for every log read below.

Step 0 — Confirm the platform itself is healthy

Before blaming the deploy, rule out the server.

1. mcp__dokploy__settings-health — must return ok.
2. mcp__dokploy__settings-checkInfrastructureHealth — checks Docker daemon, Traefik, network, disk.
3. mcp__dokploy__settings-getDockerDiskUsage — if the disk is >90% full, builds silently fail with "no space left on device". Run /dokploy-dev:cleanup to recover.
4. mcp__dokploy__settings-getDokployVersion — note the version; some bugs are version-specific.

If any of these fail, fix the server first. Do not proceed.

Step 1 — Locate the failed deployment

Find the most recent deployment for the resource and confirm its status.

For a single resource (you know the ID):

mcp__dokploy__deployment-all          → { applicationId: "<id>" }   # applications ONLY
mcp__dokploy__deployment-allByCompose → { composeId: "<id>" }       # compose stacks
mcp__dokploy__deployment-allByServer  → { serverId: "<id>" }        # server-level deploys

(deployment-all takes only applicationId — compose and server deploys have their own list tools.)

For "I don't know which app failed":

mcp__dokploy__deployment-allCentralized   # all deployments across the instance
mcp__dokploy__deployment-queueList        # what's currently queued / in-flight

In both responses, look at status. Values you care about:

Save the deploymentId of the failed run — multiple steps below take it.

Step 2 — Read the logs (build vs runtime)

Logs are the single most informative artifact. Pick the right log for the failure — the read-logs skill has the full detail; the essentials:

• Build failed (status: error, image never started) → read the build log for that deployment:

  mcp__dokploy__deployment-readLogs { deploymentId: "<from Step 1>", tail: 500 }
  

  If deployment-readLogs isn't a registered tool in your session (some MCP builds expose a reduced tool set — ToolSearch won't find it), read the identical artifact over REST instead of giving up on the log:

  curl -s -G "$DOKPLOY_URL/api/deployment.readLogs" -H "x-api-key: $DOKPLOY_API_KEY" \
    --data-urlencode "deploymentId=<from Step 1>" --data-urlencode "tail=500" | tr '\r' '\n'
  

  CLI alternative: dokploy deployment read-logs --deploymentId <id> --tail 500. Always read the actual build log before forming a root cause — a ~15s "instant" failure looks the same for a dozen different causes (corepack, lockfile, frozen-install policy, OOM), and only the log distinguishes them. See the read-logs §3 fallback for details.
• Build succeeded but the container is crashing / erroring at runtime → read the runtime log:
  • App: mcp__dokploy__application-readLogs { applicationId, tail: 300, since: "1h", search?: "error" }
  • Compose stack: read every container. First enumerate (compose-one { composeId } → appName/composeType; then docker-getContainersByAppNameMatch { appName, appType: "docker-compose" } for compose, or docker-getStackContainersByAppName { appName } for swarm). Then loop compose-readLogs { composeId, containerId, tail, since, search } for each container — or just run /dokploy-dev:compose-logs <compose>.
  • Database: {type}-readLogs { {type}Id, tail, since, search }.

tail is 1–10000 (default 100); since is all or <n>{s|m|h|d}; search is a server-side substring filter. The runtime-log .data is a newline-joined, timestamp-prefixed string.

Scan the log for these patterns first — they account for the majority of Dokploy build failures:

Step 3 — Inspect the container state

If the build succeeded but the runtime is broken, switch from build logs to container introspection.

mcp__dokploy__docker-getContainersByAppLabel
  → { appName: "<appName>", type: "standalone" }    # type is REQUIRED: "standalone" | "swarm"

Returns the list of running containers tagged with this app's Docker label (each { containerId, name, state, status }). You want to see:

• State — running, exited, restarting (crash loop)
• Health — healthy, unhealthy, starting, none
• Image — confirm Dokploy is running the image it just built (not an old one)
• Ports — what's actually published

Drill down with these as needed:

Crash loop pattern: state oscillates between restarting and exited. Always read docker-getConfig and check the RestartPolicy and the container's exit code before chasing the wrong issue.

Step 4 — Check the request path (502 / 504 / wrong content)

If the container is running but HTTPS clients see 502 / 504 / wrong response, the failure is between Traefik and the container.

mcp__dokploy__application-readTraefikConfig
  → { applicationId }

Look for:

If the resource is exposing ports directly (ports: ["80:80"] in compose), there will be a port collision with Traefik (80/443/8080). Either remove the explicit port mapping (let Traefik handle it via labels) or change the host port.

Step 5 — Recover

Pick the smallest action that unblocks the user. Always confirm destructive operations first.

Step 6 — Ask the AI to summarise (when available)

If an AI provider is configured (mcp__dokploy__ai-getEnabledProviders returns at least one), let it digest the log and recommend a fix instead of grepping manually.

ai-analyzeLogs takes the log text you already fetched in Step 2 — not a deploymentId:

mcp__dokploy__ai-analyzeLogs
  → {
      aiId:    "<id of an enabled provider from ai-getEnabledProviders>",
      logs:    "<the build- or runtime-log text from Step 2>",
      context: "build"     # for deployment-readLogs output
               | "runtime" # for application/compose/db readLogs output
    }

The response includes a natural-language root-cause summary and suggested remediation. For broader recommendations (e.g. "given this app, what should I check next?"), use ai-suggest. See the ai-assist skill for full setup and provider configuration.

If ai-getEnabledProviders returns an empty list, AI is not configured — either wire it up via ai-create + ai-testConnection, or do the analysis manually using the patterns in Step 2's table.

Step 7 — Verify the fix

After applying a fix:

1. application-redeploy (or compose-redeploy) — re-runs with the corrected config.
2. Poll deployment-all filtered by the resource ID — wait for status: done.
3. domain-validateDomain if a domain is involved.
4. docker-getContainersByAppLabel — confirm the container is running and healthy.
5. curl -sI <domain> — final HTTP 200 / expected status.

If the fix didn't take, go back to Step 1. Do not chain more fixes on top of an unverified state.

Failure mode → recovery quick reference

When to escalate

• Persistent 502 with everything green → server resource exhaustion. Check server-getServerMetrics and settings-checkInfrastructureHealth.
• Cluster / Swarm deploy failures → cluster-getNodes, swarm-getNodeInfo. Out-of-quorum nodes break Swarm deploys silently.
• Traefik returns nothing for any domain → settings-readTraefikConfig and the dynamic config under /etc/dokploy/traefik/dynamic/. A malformed dynamic config takes the whole router down.
• API endpoints returning 401 mid-session → API key was rotated or revoked. Regenerate in Settings > API/Tokens.