Troubleshoot

Dokploy Troubleshooting Reference

This is the symptom-to-cause reference table for common Dokploy problems. Match the user's symptom against the relevant section below, then apply the fix.

For a failed deployment, start here: Run /dokploy-dev:debug [resource] (or load the debug-deploy skill). That runs the full decision tree — failed-run lookup, build log analysis, container/Traefik inspection, optional AI summary, and recovery — instead of just a symptom lookup. Use this skill when you already know the rough symptom and want the table entry.

Quick Diagnostics Checklist

Run these checks first to understand the current state:

1. Platform health:

   mcp__dokploy__settings-health
   mcp__dokploy__settings-checkInfrastructureHealth
   mcp__dokploy__settings-getDockerDiskUsage
   

2. Dokploy version: Call mcp__dokploy__settings-getDokployVersion

3. Recent deployments: Call mcp__dokploy__deployment-allCentralized

4. Docker containers: Call mcp__dokploy__docker-getContainers

If the health check fails or checkInfrastructureHealth reports a problem, the server itself is unhealthy. Fix the server before investigating application-level issues.

Domain Issues

Domain debugging steps

1. Verify DNS resolves to the correct IP:

   dig +short example.com
   

2. Check if Traefik is receiving the request:

   curl -vk https://example.com 2>&1 | head -30
   

3. Verify the domain configuration in Dokploy: Call mcp__dokploy__application-one with the applicationId and inspect the domains array.

4. Validate the domain: Call mcp__dokploy__domain-validateDomain with domain (the hostname string, NOT the domainId; optionally serverIp).

Deployment Failures

For a multi-step diagnosis instead of a single-row lookup, run /dokploy-dev:debug — it locates the failed run, reads the build log, inspects the container, and recommends a fix.

Deployment debugging steps

For full diagnosis, prefer /dokploy-dev:debug <id> over walking these manually — it chains them in the right order and also runs ai-analyzeLogs if a provider is configured.

1. List deployments and find the latest:

   curl -s -H "x-api-key: $DOKPLOY_API_KEY" \
     "$DOKPLOY_URL/api/deployment.all?applicationId=<id>" | python3 -m json.tool
   

   Or call mcp__dokploy__deployment-all with applicationId as the filter. Save the deploymentId of the failed run and its logPath.

2. Read the logs (build vs runtime):

   • Build failure → mcp__dokploy__deployment-readLogs { deploymentId, tail: 500 } (the build log for that run).
   • Runtime crash → mcp__dokploy__application-readLogs { applicationId, tail, since, search } for an app, or the per-container compose-readLogs loop for a stack. These return live container stdout/stderr (v0.29.0+ — no SSH/Beszel needed). See the read-logs skill.

3. Check application status: mcp__dokploy__application-one with the applicationId. Look at the applicationStatus field.

4. Inspect the container: mcp__dokploy__docker-getContainersByAppLabel { appName } for state and health. Drill down with docker-getConfig { containerId } to see env, command, mounts, network, and restart policy. If the container is in a restart loop, the exit code in docker-getConfig tells you why.

5. Check Traefik routing (if HTTP errors): mcp__dokploy__application-readTraefikConfig returns the router/service entries Traefik uses for this app. Confirm the service URL points at the right port and the host matches the domain the user is hitting.

6. Summarise with AI (optional): If mcp__dokploy__ai-getEnabledProviders returns a provider, fetch the log text (step 2) and run mcp__dokploy__ai-analyzeLogs { aiId, logs, context: "build" | "runtime" } for a natural-language root-cause + suggested fix. See the ai-assist skill for setup.

Database Issues

Database connection string patterns

For external access, replace container-name with the server IP and use the external port.

Docker / Compose Issues

Compose debugging steps

1. Validate the compose file: Call mcp__dokploy__compose-getConvertedCompose with the composeId.

2. Check running services: Call mcp__dokploy__compose-loadServices with the composeId (defined services), and mcp__dokploy__docker-getContainersByAppNameMatch { appName, appType: "docker-compose" } for the actual running containers + their state.

3. Read each container's logs over MCP (no SSH needed): For every container returned in step 2, call mcp__dokploy__compose-readLogs { composeId, containerId, tail, since, search }. The /dokploy-dev:compose-logs <name> command runs this whole loop and highlights errors per container.

MCP Connection Issues

Diagnostic Commands

Via curl

# Check Dokploy server health
curl -s "$DOKPLOY_URL/api/settings.health" \
  -H "x-api-key: $DOKPLOY_API_KEY"

# Check Dokploy version
curl -s "$DOKPLOY_URL/api/settings.getDokployVersion" \
  -H "x-api-key: $DOKPLOY_API_KEY"

# List all Docker containers
curl -s "$DOKPLOY_URL/api/docker.getContainers" \
  -H "x-api-key: $DOKPLOY_API_KEY"

# Get server public IP
curl -s "$DOKPLOY_URL/api/server.publicIp" \
  -H "x-api-key: $DOKPLOY_API_KEY"

# List all projects with their applications
curl -s "$DOKPLOY_URL/api/project.all" \
  -H "x-api-key: $DOKPLOY_API_KEY"

Via MCP tools

mcp__dokploy__settings-health
mcp__dokploy__settings-getDokployVersion
mcp__dokploy__docker-getContainers
mcp__dokploy__server-publicIp
mcp__dokploy__project-all

When to Escalate

• Traefik configuration issues — Check the Traefik dashboard (usually at port 8080 on the server). Traefik misconfigurations are outside Dokploy's control.
• Docker Swarm / cluster issues — Check node status with mcp__dokploy__cluster-getNodes. Cluster problems require server-level debugging.
• Persistent 502s after all checks pass — Check server resources (CPU, memory, disk). The server may be under-provisioned.
• Data corruption — If database data is corrupted, restore from backups. Enumerate configured backups per resource and list backup files with mcp__dokploy__backup-listBackupFiles (backup-all was removed — backups are now resource-scoped).
• Dokploy upgrade failures — Check the Dokploy GitHub releases for known issues. Roll back to the previous version if needed.
• Running < v0.29.13? Upgrade — v0.29.13 fixed ~20 security issues (OS command injection in git/docker/db paths, cross-org IDORs, credential disclosure, unauthenticated WebSocket handlers).