Troubleshooting

The problems people actually hit, and how to tell which one you have.

A server is stuck on "pending"#

The record exists but the agent has never checked in. SSH in and look:

sudo systemctl status cloudpilot-agent
sudo journalctl -u cloudpilot-agent -n 50 --no-pager

Usual causes:

• Outbound HTTPS is blocked. The agent dials out; if it cannot reach the internet, it cannot check in.
• The install failed partway and left the service stopped. The journal will say where.

A server went offline#

Your sites are still up — the agent is not in the request path. What you have lost is panel control of that machine.

sudo systemctl restart cloudpilot-agent

If it will not stay running, read the journal. If the machine itself is unreachable, this is a server problem rather than a CloudPilot one; your provider's console is the next stop.

A domain is not loading#

Work through it in order, because each step depends on the one before:

1. Does DNS point here?

dig +short yourdomain.com @8.8.8.8

Nothing printed means the record is missing or has not propagated. A different IP means the domain points somewhere else — often a parked page at the registrar.

2. Is there a web server configuration for it? Check the server's Domains tab. A domain with DNS but no configuration reaches your server and gets whatever the default site is, which is usually not what you wanted.

3. Is there a certificate? If HTTP works and HTTPS does not, the certificate is missing or failed to issue.

The domain readiness check on the Domains tab reports all three, which is faster than guessing.

A certificate will not issue#

Almost always DNS. The certificate authority proves you own the domain by making a request to it; if that request does not arrive at this server, issuing fails.

Confirm with dig that the domain resolves to this server's IP, then retry. If DNS is correct, check that port 80 is open — the validation request uses it, even for an HTTPS certificate.

"Permission denied"#

Your role does not include that action. See Roles and permissions for what each role holds, and ask an Owner or Admin if you need more.

If you are an Owner and still seeing this, it is worth reporting — that combination usually means something is wrong rather than that you lack access.

A deploy failed#

Read the deploy log. The error is in it, and retrying without reading it will usually fail the same way.

Common ones:

• Wrong runtime. A React app deployed as node_pm2 instead of static will not behave. See choosing a runtime.
• Build failed. Fix it locally first — if it does not build on your machine, it will not build on the server.
• Out of disk. Check the server's Overview. This is what disk alerts are for.

A deploy is "waiting for approval"#

The project is protected. Someone else has to approve it. That is the feature working, not a fault.

The site still shows the old version#

Your browser is probably holding the old files. Hard-reload (Ctrl/Cmd + Shift + R) and check again, and confirm in the deployment history that the deploy actually finished.

A firewall rule undid itself#

That is the safety net. A rule that is not confirmed within 60 seconds is reverted, because losing contact is what happens when a rule locks you out. See Firewall.

CloudPilot keeps asking for database credentials#

It does not store them, by design. They live in the browser tab you typed them into and are gone when you close it. See Databases.

A server says I need to upgrade#

You have more servers than your plan allows, so the extras are locked. The machine is still running and still serving traffic — what you have lost is panel access to it. Upgrade, or disconnect a server you no longer need. See The server limit.

A push to GitHub did not deploy#

Check GitHub's Recent Deliveries for the webhook first — it shows whether the request was even sent and what came back. A 401 there means the secret does not match. See Auto-deploy from GitHub.

Still stuck#

Contact support — with the server or project name, what you expected, what happened, and the relevant log output.