Deployment Diagnosis

When a deployment fails, understanding the root cause can be time-consuming — especially when the error is buried in a long log or involves multiple interacting systems. Devpilot's deployment diagnosis feature uses AI to analyze your failed deployment, classify the failure, identify the affected step, and suggest specific fixes you can apply.

How deployment diagnosis works

When a deployment fails, Devpilot captures every hook's output and exit code. The diagnosis feature feeds that data — along with context about your application and platform — into an AI model. The model produces a structured diagnosis that Devpilot stores alongside the deployment, so anyone on your team who opens the failed deployment sees the same analysis.

Each diagnosis records:

• Category — The class of failure (see the list below).
• Severity — High or Critical, indicating how much it impacts deployment.
• Affected step — The hook where the failure originated (for example, "Install Dependencies", "Build Application", "Run Migrations", "Clone project from version control", or "Cache Views").
• Root cause — A plain-language explanation of what went wrong.
• Suggested fixes — One or more concrete actions you can take, ordered by likelihood of resolving the issue.
• AI model used and analysis duration — For transparency about which model produced the diagnosis and how long it took.

Diagnosis categories

Diagnoses fall into these categories, which Devpilot uses to route you to the right fix guidance:

Using the Diagnose feature

Recurring failure patterns

When the same failure signature appears across multiple deployments for an app, Devpilot records it as a failure pattern and tracks how often it has occurred. This helps you spot issues that are not one-offs — for example, a server that consistently lacks the right PHP extensions — and address them at the root rather than retrying deployments. The pattern history includes the list of affected deployments, the first and last times it occurred, a suggested permanent fix, and whether the pattern is resolved.

Examples of diagnoses Devpilot produces

These examples are representative of diagnoses Devpilot has surfaced on real deployments:

• Dependency failure on Install Dependencies (critical): "The 'npm' command is not installed or accessible in the deployment environment, preventing the installation of project dependencies."
• Dependency failure on Build Application (high): "The 'next' command required for building the application was not found, indicating that the Node.js runtime or required global dependencies are missing on the server."
• Dependency failure on Install Dependencies (critical): "Composer dependency installation failed because the required PHP extensions 'ext-simplexml' and 'ext-dom' are not installed on the server."
• Git failure on Clone project from version control (critical): "The deployment process failed because the SSH connection could not be initialized. This is due to the absence of a private key required for SSH key authentication."
• Dependency failure on Cache Views (high): "The PHP artisan command failed because the required vendor/autoload.php file is missing, indicating that composer install either did not execute successfully or the vendor directory was not properly created during the deployment."

Tips for effective troubleshooting

• Read the affected step first. The diagnosis tells you exactly which hook failed. Start there rather than scrolling through the entire log.
• Check the category. A Dependency failure almost always means something is missing on the server; a Git failure points to SSH or repo access; a Database connection failure points to credentials or network reachability.
• Fix the root cause, not the symptom. If a build fails because a binary is missing, install the binary; do not disable the hook.
• Use failure patterns. If the same failure has occurred several times, address it permanently rather than just retrying.

Next steps