Backups Troubleshooting
Diagnose and fix common Devpilot backup problems — destination failures, stuck jobs, failed restores, unhealthy real-time streams, and billing-driven suspensions.
Backups Troubleshooting
Most backup problems fall into a small set of patterns. This page walks through each one, what it usually means, and how to unblock yourself.
Before you dive in, make sure you know:
- Which plan you're troubleshooting (Backups > Plans).
- Its latest history row (Backups > History), and the row's error message if it has one.
- The destination the plan writes to, and whether it is still marked Active.
Destination Test Connection Fails
When you click Test Connection on a destination and it returns an error, the most common culprits are:
| Symptom | Likely cause | Fix |
|---|---|---|
| "Authentication failed" / "Access denied" | Wrong credentials (key, secret, password). | Re-enter credentials, making sure there are no trailing spaces. |
| "Connection refused" / "Timed out" | Firewall, VPN, or wrong host/port. | Check the host is reachable from Devpilot, and that outbound traffic is allowed. |
| "Container not found" / "Bucket not found" | Bucket or container does not exist, or the account doesn't have permission to list it. | Create the bucket/container or grant the needed IAM permissions. |
| "SSL/TLS error" | Certificate or TLS version mismatch. | Confirm the destination endpoint accepts modern TLS and uses a valid certificate. |
Until a destination tests green, plans that write to it will queue but fail to upload. Fix the destination first, then retry the plan.
Discover Databases Fails
When you add a server-based source, Devpilot tries to list the databases on it. If that step fails:
| Symptom | Likely cause | Fix |
|---|---|---|
| "SSH connection failed" | The server's SSH credentials are wrong or the host is unreachable. | Test SSH into the server with the same credentials before retrying. |
| "Access denied for user" | The database user cannot see the server's databases. | Grant the user at least SHOW DATABASES (MySQL) or CONNECT on the relevant databases (PostgreSQL). |
| "mysql: command not found" / "psql: command not found" | The client binary Devpilot needs for discovery is missing on the server. | Install the matching client (mysql-client or postgresql-client) and retry. |
| Empty database list | The user has credentials but no visibility of any database. | Grant the user privileges on at least one database. |
Backup Stuck in Pending or In_Progress
If a backup has not moved for an unreasonable amount of time:
Open the History Row
Go to Backups > History and click into the stuck run. If there's an error message, it will explain itself — start there.
Check the Destination
Confirm the destination still tests green. Backups stuck in In_Progress are most often waiting on a destination that is no longer reachable.
Cancel the Run
From the history row, click Cancel. Only backups in Pending or In_Progress can be cancelled; the status moves to Cancelled.
Retry
Trigger the plan again manually. Fresh backups start in Pending and should move to In_Progress quickly if the destination is healthy.
Backup Failed
A Failed history row always carries an error message. Common patterns:
| Error pattern | What it means | What to do |
|---|---|---|
| "Could not connect to source" | Source host or credentials are broken. | Re-test the source connection; update credentials. |
| "Access denied" during dump | DB user lacks privileges on the database being backed up. | Grant SELECT (and LOCK TABLES where needed) on the source database. |
| "No space left on device" | Server ran out of disk while Devpilot was preparing the dump. | Free space on the server or move to a destination that streams directly. |
| "Upload failed" / "Failed to write to destination" | Credentials or network between Devpilot and the destination broke mid-run. | Re-test the destination; retry the plan. |
| "Timeout" | The dump took longer than the allowed window. | For very large databases, split into smaller logical plans where possible. |
After fixing the underlying cause, trigger the plan again. Devpilot does not automatically retry failed runs.
Restore Failed
| Error pattern | What it means | What to do |
|---|---|---|
| "Source backup not completed" | You tried to restore a backup that is not in Completed. | Wait for the backup to finish, or pick a different, completed backup. |
| "Target refused connection" | Target server is unreachable from Devpilot. | Verify the target host/port and try again. |
| "Database already exists" | You tried to restore in-place without enabling overwrite. | Either turn on Replace existing data or set a new Target database name. |
| "Insufficient privileges on target" | Target DB user cannot create or write to the target database. | Grant the restore user privileges on the target database. |
| "Download failed" | The destination storing the backup file is no longer reachable. | Fix the destination and retry the restore. |
If the restore moves to Failed, assume the target is partially written. Either retry with Replace existing data turned on, or clean the target before the next attempt. See Restore for the full flow.
CDC Stream Stuck in Starting or Flipping to Error
Real-time streams depend on the source's change log. If a stream won't stabilize:
Open the Stream
Go to the real-time plan and open the Stream tab. Check the Status — is it stuck in Starting, or is it bouncing in and out of Failed?
Read the Error Message
The Error message field on the stream summarizes the most recent problem. Common ones:
- "Replication privilege missing" — grant
REPLICATION SLAVEandREPLICATION CLIENT(MySQL) or the matching replication role (PostgreSQL). - "binlog format not ROW" — MySQL binlogs must be in ROW format.
- "Replication slot not found" — recreate the PostgreSQL replication slot.
- "Connection timed out" — the source is no longer reachable.
Check Health
Click Check Health on the stream. Devpilot returns the latest health snapshot — events captured, current lag, and the last event time. A healthy stream has near-zero lag and a recent last-event time.
Read the Logs
Click View Logs on the stream. The most recent log lines usually pinpoint the exact failure.
Stop, Fix, Restart
If the error is at the source (missing privilege, wrong binlog format), fix it on the database. Then Stop the stream and Start it again from the plan. Repeated Error transitions without a stop usually mean the same underlying problem is still there.
A stream stuck in Starting for a long time is often finishing the initial snapshot of a very large source. Check the log for snapshot progress before assuming it is broken.
For stream concepts, see Real-Time Backup.
Billing-Driven Suspension
When a backup plan's billing status shows Suspended, scheduled backups on that plan will not run until billing is healthy again.
Identify the Failing Plan
On Backups > Plans, plans with a billing problem show a red Suspended or Failed badge. Click in to confirm the billing status and see how many charge attempts have failed.
Update Your Payment Method
Go to Settings > Billing > Payment Methods and add a fresh card or update the existing one. See Payment Methods.
Reattach to the Plan
On the suspended backup plan's Billing tab, pick the working payment method. Devpilot retries the charge.
Confirm Back to Active
After a successful charge, the plan returns to Active and the failed-attempts counter resets to zero. Scheduled backups resume on the next run.
See Pricing and Billing for the full billing model.
Storage Destination Support
All destination types Devpilot exposes today have working drivers, so any of them can be used for real backups.
| Destination | Status |
|---|---|
| Local | Available |
| S3 | Available |
| SFTP | Available |
| Azure Blob | Available |
| Google Cloud Storage (GCS) | Available |
| Google Drive | Available |
| Cloudinary | Available |
If a destination type is missing from the picker when you create a destination, it means your workspace hasn't been granted access to that destination type — contact your admin to enable it.
Still Stuck?
If none of the patterns above match, pick up the exact error message from the failing history row or stream and search the main Troubleshooting section. Providing that error message verbatim makes it much faster to get help.
Next Steps
Pricing and Billing
Understand how Devpilot measures backup storage, calculates monthly cost for each plan, and charges the payment method attached to the plan.
Understanding Integrations
Learn how integrations connect external services to your Devpilot workspace for deployments, server provisioning, and notifications.