Troubleshooting Overview
General debugging approach, where to find information, and how to get help when things go wrong in Devpilot.
When something goes wrong in Devpilot, the dashboard surfaces the information you need in a predictable set of places: deployment detail pages, server detail pages, error tracking, and your billing page. This guide walks through how to narrow down an issue and where to look first.
General debugging approach
Identify which area is affected
Devpilot groups issues into a few distinct categories. Identifying the right one points you at the right screen:
- A deployment did not finish. The deployment status is Failed or Cancelled.
- A server is not reachable. The server card shows Inactive, or the connection indicator is red.
- A server provision (creating a new server) stopped partway. The provision status shows Failed or Rolled back.
- Your application throws runtime errors after a successful deployment. These show up under Error Tracking, not deployments.
- A payment or subscription is blocking access. The billing page shows a Pending or Cancelled payment, or an Inactive subscription.
Open the deployment detail page
If a deployment failed, navigate to Apps > [Your App] > Deployments and open the deployment. Each deployment runs through five hook stages in this order:
- Pre Execution — runs before anything else
- Pre Source Control — runs right before Devpilot fetches the code
- Post Source Control — runs right after the code is fetched
- Post Setup — runs after the app's runtime is set up (dependencies installed, assets built)
- Post Release — runs after the new release is made live
The first hook that shows a Failed status is the one to focus on. Every hook stores its command, output, exit code, and duration.
Read the AI diagnosis
When a deployment fails, Devpilot automatically runs an AI diagnosis and attaches it to the deployment. The diagnosis block shows:
- A category — one of Dependency failure, Runtime error, Git failure, Configuration error, or Database connection.
- A severity — Critical, High, Medium, or Low.
- An affected step — the exact hook where the failure occurred.
- A root cause paragraph explaining what went wrong.
- One or more suggested fixes, some of which can be applied in one click.
If a fix is marked auto-applicable, you can apply it directly from the deployment page. Devpilot then either patches the failing hook or adds a new one and lets you redeploy.
Check recurring failure patterns
Devpilot groups repeated failures across an app into failure patterns. Open Apps > [Your App] > Insights to see patterns grouped by category (for example, multiple Dependency failure events across different deployments). A pattern usually points at a configuration problem that is worth fixing at the source rather than patching per deployment.
Check server and provisioning status
For connection or provisioning problems, open Servers > [Your Server]. The header shows:
- Status — Active or Inactive.
- Connection status — live SSH reachability.
- Provisioning status — Provisioned once initial setup completed.
If the server was provisioned through Devpilot, the provisioning page shows the step that failed (for example Plan, Apply, Test SSH, or Install agent) and the message returned.
Review error tracking for runtime issues
Post-deployment errors from your running app appear under Monitoring > Error Tracking. Errors are grouped by class name and file/line, and each group shows occurrences, last seen time, and affected users and devices. Runtime errors are not visible in deployment logs — they come from your application at request time.
Contact support if needed
If the steps above did not resolve the issue, contact Devpilot support. See "How to contact support" below.
Where to find what
| What you are looking at | Where to look |
|---|---|
| A deployment that will not finish | Apps > App > Deployments > open the deployment |
| The specific hook that failed | Deployment detail > hook list (look for Failed status) |
| AI root cause and suggested fix | Deployment detail > Diagnosis panel |
| Recurring deployment problems | Apps > App > Insights (failure patterns) |
| Application exceptions at runtime | Monitoring > Error Tracking |
| A server that is offline | Servers > Server (check Status and Connection status) |
| A new server that failed to come up | Servers > Provisions (check the failing step) |
| A failed payment or expired plan | Account > Billing |
Using AI diagnosis
Every failed deployment is eligible for AI diagnosis. The diagnosis reads the deployment data, hook output, and the actual command that failed, then produces:
- A category that matches one of the five the system tracks: Dependency failure, Runtime error, Git failure, Configuration error, Database connection.
- A plain-language root cause.
- Suggested fixes with a confidence score. Fixes marked as auto-fixable can be applied from the UI — for example, adding a Post Setup hook that installs a missing package, or updating an existing hook's command.
After applying a suggested fix, Devpilot records whether the next deployment succeeded so recurring patterns improve over time. Check the Insights tab to see if the same pattern stops appearing.
Common issue categories
Deployment Errors
Failures during any of the five hook stages (Pre Execution, Pre Source Control, Post Source Control, Post Setup, Post Release). Covers the five diagnosis categories the system uses: dependency, runtime, git, configuration, and database connection.
Connection Issues
Servers showing Inactive, failed SSH reachability, and provisioning failures at steps like Test SSH or Install agent.
Billing Issues
Payments stuck in Pending, Cancelled transactions, Inactive subscriptions, and updating payment gateways (Stripe, PayPal, Flutterwave).
How to contact support
Contact Devpilot support if:
- You have followed the relevant troubleshooting guide and the issue persists.
- A server is unreachable and the provisioning or connection steps do not explain why.
- A payment was charged but the subscription did not activate.
- You suspect a platform bug rather than a configuration problem.
Reach support through the Help menu in the dashboard (attaches workspace context automatically), or through the support email on your account page.
When you open a ticket, include:
- Workspace name and the affected app or server name
- Deployment ID or provision ID if the issue involves one
- Screenshots of the error or diagnosis panel
- Timestamp of when the issue started
Never share API keys, SSH private keys, or passwords with support. Devpilot staff will never ask for these.
Preventive measures
- Let the AI diagnosis run on every failed deployment — the suggested fixes are free and often one-click.
- Review your app's Insights tab weekly for failure patterns that repeat. Fixing the pattern once is cheaper than patching each deployment.
- Keep the payment method on your billing page current so automatic renewals do not fall into Pending.
- Use the Servers page to confirm Connection status and Provisioning status before triggering a deployment onto a new server.