Troubleshooting

Common issues and how to resolve them.

SSH Connection Fails

The platform cannot connect to your server over SSH.

Check these:

1. IP address — verify the server IP in your dashboard matches the actual server IP.
2. Port 22 — confirm SSH is running and port 22 is open in your firewall.
3. Firewall rules — if you use a cloud firewall (AWS Security Groups, DigitalOcean Firewall, etc.), ensure port 22 is allowed from all sources or at least from ServerPlane's IP.
4. SSH credentials — the SSH key on the platform must match the authorized key on the server. Re-check under Server Settings.
5. SSH service — on the server, run systemctl status sshd to confirm the SSH daemon is running.

Server Stuck in Provisioning

The server was added but provisioning never completes.

Check these:

1. SSH access — try connecting manually: ssh serverplane@YOUR_SERVER_IP. If this fails, see the SSH section above.
2. Server logs — check the provisioning log in the server detail page for specific error messages.
3. Fresh OS — provisioning expects a clean Ubuntu 24.04 installation. Pre-existing configurations (especially for Nginx, Apache, or PHP) can cause conflicts.
4. Resources — ensure the server has at least 512 MB of RAM and sufficient disk space for package installation.

Deployment Fails

An application deployment does not complete successfully.

Check these:

1. Domain DNS — if your app uses a custom domain, verify the A record points to the server's IP address. Use dig yourdomain.com to confirm.
2. Server resources — check that the server has enough RAM and disk space. Out-of-memory errors are a common cause of failed builds (especially Node.js).
3. App logs — check the deployment log in the app detail page. The log shows each step and where the failure occurred.
4. Build commands — for Node.js and Python apps, ensure your build commands (e.g., npm install, pip install) are correct and that required runtime versions are available.
5. File permissions — ensure the application directory is owned by the correct user.

SSL Provisioning Fails

Let's Encrypt SSL certificate issuance does not complete.

Check these:

1. Domain DNS — the domain's A record must point to your server's IP address. Let's Encrypt validates domain ownership via HTTP, so DNS must be fully propagated.
2. Port 80 open — Let's Encrypt uses HTTP-01 challenge validation, which requires port 80 to be open and accessible from the internet.
3. No existing certificate — if a certificate already exists for the domain, the renewal may behave differently. Check /var/log/letsencrypt/letsencrypt.log on the server.
4. Rate limits — Let's Encrypt enforces rate limits (50 certificates per registered domain per week). If you have been issuing many certificates, you may need to wait.

Database Connection Issues

Your application cannot connect to its database.

Check these:

1. Engine running — on the server, check the database service status:
   • MariaDB: systemctl status mariadb
   • PostgreSQL: systemctl status postgresql
   • MongoDB: systemctl status mongod
2. Credentials — verify the database name, username, and password in your app's environment variables match what was created in the Databases section.
3. Host — for apps on the same server, use 127.0.0.1 or localhost as the database host.
4. Port — confirm the default port is correct: MariaDB (3306), PostgreSQL (5432), MongoDB (27017).

Agent Shows Offline

The server agent is installed but shows as offline in the dashboard.

Check these:

1. Agent service — on the server, check if the agent systemd service is running:

   systemctl status serverplane-agent
   

2. Restart the agent — if the service is stopped or failed:

   systemctl restart serverplane-agent
   

3. Network — the agent needs outbound HTTPS access to communicate with https://serverplane.xyz. Check that outbound connections on port 443 are not blocked.
4. Logs — check agent logs for errors:

   journalctl -u serverplane-agent —no-pager -n 50
   

File Upload Fails

Uploading a file through the file manager does not complete.

Check these:

1. File size — the file manager has a maximum upload size limit. Large files should be transferred via SFTP instead.
2. Disk space — ensure the server has sufficient free disk space. Run df -h on the server to check.
3. Permissions — the target directory must be writable by the application user.
4. Network timeout — very large files or slow connections may cause the upload to time out. Use SFTP for files larger than a few megabytes.