Deployment Errors
Solutions for failed deployments in Devpilot, organized by the AI diagnosis categories the platform actually uses.
A deployment in Devpilot finishes in one of these statuses: Completed, Failed, or Cancelled. When a deployment is Failed, Devpilot automatically classifies the root cause into one of five categories. This page is organized around those five categories so you can match what the diagnosis shows you to a concrete fix.
Reading a failed deployment
Open the deployment
Go to Apps > [Your App] > Deployments and open the one with the Failed badge. The page shows the commit, the trigger, the committer, duration, and the full hook list.
Find the failing hook
Each deployment runs hooks across these five stages, in order:
- Pre Execution
- Pre Source Control
- Post Source Control
- Post Setup
- Post Release
Scan down the hook list for the first one with status Failed. Hooks that appear after it will show Skipped. The failing hook stores the exact command that ran, the exit code, stdout, and stderr.
Read the diagnosis
The Diagnosis panel shows the category, severity, affected step, root cause, and one or more suggested fixes. If a fix is marked auto-applicable, you can apply it from the panel and trigger a new deployment.
Errors by diagnosis category
The system classifies every failure into one of five categories. Pick the section that matches the label on the Diagnosis panel.
Dependency failure
The Dependency failure category covers anything where a required runtime, package, or extension was missing on the server or could not be installed.
| Common affected step | What went wrong | What to do |
|---|---|---|
Install Dependencies (Post Setup) | The package manager (npm, composer, pip, etc.) was not found, or a command like next, artisan, or vite was not available. | Apply the suggested fix — it typically adds a Post Setup hook that installs the missing runtime (for example apt-get install -y nodejs npm). Otherwise, add a setup hook yourself under Apps > App > Hooks. |
Build Application (Post Setup) | A build tool (e.g. next build, vite build) failed because its framework was not installed. | Check that your app's install step actually ran to completion. If npm install succeeded but next is still missing, your lockfile and manifest may be out of sync — regenerate the lockfile locally and push. |
Install Dependencies with "missing PHP extensions" | The server is missing PHP extensions like ext-dom or ext-simplexml. | Apply the suggested fix to install the extension, or open the server page and ensure the PHP version you selected includes the required modules. |
Any setup step with vendor/autoload.php missing | Composer install either did not run or did not finish. | Re-trigger the deployment. If it keeps failing, verify that a composer install hook exists in the Post Setup stage. |
Runtime error
The Runtime error category covers errors thrown by the build or application binary itself — not missing packages, but the command ran and failed.
| Common affected step | What went wrong | What to do |
|---|---|---|
Build Application | A compile step returned a non-zero exit code (TypeScript errors, broken imports, invalid syntax). | Open the hook output for the exact compiler message. Fix it in your code, push, and deploy again. |
| Any Post Setup or Post Release hook ending with a non-zero exit | A script ran but threw an exception. | The hook output contains the stack trace. Treat it the same way you would on a local machine — the exit code and the last few lines of output are the actionable part. |
Runtime errors in a shipped (running) application — uncaught exceptions at request time — do not appear here. They appear under Monitoring > Error Tracking, grouped by class name and location.
Git failure
The Git failure category covers problems cloning or pulling the repository around the Pre Source Control / Post Source Control stages.
| Symptom | Cause | What to do |
|---|---|---|
| Failure with "private key required" or "could not initialize SSH" | The server does not have the Git deploy key configured. | Open Servers > [Server] > SSH Keys and verify the key Devpilot registered exists on the server. Reconnect the Git provider under Integrations > Git if needed. |
| Failure with "repository not found" | The repo URL is wrong or the connected account lost access. | Verify the repository under Apps > [App] > Settings and reconnect the Git provider. |
| Failure with "branch not found" | The configured branch was renamed or deleted. | Update the branch under Apps > [App] > Settings > Deployment. Branch names are case-sensitive. |
Configuration error
The Configuration error category covers failures where the command ran but was misconfigured — wrong path, missing env var, bad argument.
| Common affected step | What went wrong | What to do |
|---|---|---|
Install Dependencies | A hook command referenced a directory or file that does not exist. | Compare the path in the hook command against the project layout. Edit the hook under Apps > [App] > Hooks. |
Clone project from version control | The source directory configured on the app does not exist in the repo. | Update the source directory field on the app's settings page to match the path in your repo. |
| Any stage with "missing env var" | A command read an environment variable that is not set on the app. | Add or correct the variable under Apps > [App] > Environment, then redeploy. |
Database connection
The Database connection category covers failures where a migration or setup task could not reach the database.
| Common affected step | What went wrong | What to do |
|---|---|---|
Run Migrations | The database credentials used during deployment do not reach the database (wrong host, wrong port, wrong user). | Verify the database environment variables on the app match the database the server is supposed to talk to. Confirm the database accepts connections from the server's IP. |
Run Migrations with "access denied" | The DB user exists but lacks permission to run migrations. | Grant the user the required privileges on the target database, or use a privileged user for migrations. |
| Any stage with "connection refused" | The database service is not running, or a firewall drops the connection. | Confirm the database server is online and that its firewall allows inbound traffic from your application server. |
Hook failures in general
Every failure shows up as a hook with status Failed. The hook record stores:
- The stage it ran in (Pre Execution, Pre Source Control, Post Source Control, Post Setup, or Post Release)
- The action type (Shell Command for scripts, Sync File or Sync Directory for file sync)
- The exact command
- The exit code
- The captured stdout and stderr
- The duration
When reading a hook:
- A non-zero exit code with a clear error message usually points at the root cause.
- A hook showing Skipped means a previous hook failed — do not investigate skipped hooks first.
- A hook showing Processing for longer than expected means it may still be running — wait before retrying.
Cancellation vs failure
A deployment with status Cancelled was stopped by a user (via the cancel button) or by a newer deployment superseding it. There is no diagnosis for cancelled deployments because nothing failed — simply start a new deployment when you are ready.
When to apply an auto-fix
Suggested fixes marked as auto-fixable with a confidence score of 0.9 or above are generally safe to apply directly. They add or update a hook and leave your app in a state where the next deployment should succeed. Lower-confidence suggestions are worth reading but may need a tweak before you apply them.
General tips
- Always check the first Failed hook. Everything after is consequence, not cause.
- Use the Insights tab on the app. If the same pattern signature keeps appearing, fix it at the source (your repo or your server configuration) rather than patching per deployment.
- Keep your Post Setup hooks idempotent so re-running a deployment does not fail on the second try.
- If a Dependency failure keeps returning after you applied a setup hook, your server may be rebuilt between deployments in a way that does not persist the install — use the Server Packages section to install long-lived runtimes instead.