Deployment Failed — First-Response Playbook
Who this is for
Anyone whose site or app deployment just failed, and who needs to diagnose and recover quickly.
Step 1 — Identify the Failure Point
Open the Activity Center and find the failed deployment job. Expand it to see which step failed and read the error message.
Deployments have several phases that can fail independently:
| Phase | What can go wrong |
|---|---|
| SSH connection | Server unreachable, SSH key expired or wrong user |
| Package install | apt/yum error, no internet, disk full |
| File copy / git clone | Git token expired, SSH key not added to git provider |
| Build | npm/composer/pip install error, syntax error in code |
| Database migration | Schema mismatch, DB credentials wrong |
| Nginx/web server reload | Nginx config error, port conflict |
| SSL provisioning | DNS not pointed at server, port 80 blocked |
Step 2 — Read the Error Message
The Activity Center shows the raw error output from the server. Look for:
- Permission denied → SSH user (
cloudpilot) doesn't have access to the target directory. - No space left on device → Server disk is full. Free disk space or resize the disk.
- Could not connect to git → Git token is expired or the repository is private. Re-authenticate git provider.
- Nginx: configuration file test failed → Nginx config syntax error. Check the site's domain and configuration.
- Connection refused / Host unreachable → SSH is down on the server. See KB-12-05: SSH Unreachable Playbook.
Step 3 — Check the Deployment History
For sites: Site detail → Deployments tab — shows all past deployments and their status. For apps: App detail → Deployments tab — same.
If the previous deployment succeeded and only the latest failed, the change you deployed caused it. Consider rollback (Step 4) while you fix the issue.
Step 4 — Roll Back if the Site is Broken
If the site or app is currently broken for users:
For sites:
- Go to Site detail → Deployments tab.
- Find the last successful deployment.
- Click Rollback next to it.
For apps:
- Go to App detail → Deployments tab.
- Click Rollback on the last working image/commit.
See KB-03-06: Rollback a Site Deployment or KB-04-11: App Deployment History and Rollback.
Step 5 — Fix the Root Cause and Redeploy
After rolling back to restore service:
- Identify the root cause from the error message (Step 2).
- Fix the issue (update code, rotate credentials, free disk space, fix Nginx config).
- Trigger a new deployment.
Common Deployment Errors and Fixes
| Error message | Fix | |
|---|---|---|
SSH_NOT_CONFIGURED | Add SSH key to the server — see KB-02-08 | |
No space left on device | Resize disk or delete old files — see KB-02-10 | |
MISSING_STACK | Server needs LEMP/LAMP stack — provision with stack or install manually | |
DOMAIN_CONFLICT | Domain already used on this server — use a unique domain | |
UNSUPPORTED_OS | Server OS not supported for sites (must be Linux/managed) | Deploy on a supported server |
| Git clone fails | Git token expired → reconnect git provider | |
| npm/composer install fails | Check build logs for missing packages or version conflicts |
Related Articles
- KB-12-05: SSH Unreachable Playbook
- KB-12-16: Emergency Rollback Playbook
- KB-12-02: SSL Issue Playbook
- KB-03-06: Rollback a Deployment