Troubleshooting

This page provides quick fixes for common issues. For in-depth troubleshooting, check the specific feature pages linked throughout.

Server Issues

Server Stuck in PROVISIONING

Cause: Health check can’t connect to the server. Common reasons: runner agent not installed, missing Docker on the target server, or outbound connectivity blocked.

Fix:

1. Verify the runner agent is running: sudo systemctl status reoclo-runner
2. Ensure Docker is installed: docker --version
3. Check the server logs in the dashboard for specific errors

For more details, see Runner Servers.

”git not found” or “docker not found”

Cause: Required tools aren’t installed on the target server.

Fix:

sudo apt update
sudo apt install -y git docker.io curl

Verify installations: which git docker curl

Runner Agent Issues

Runner Won’t Connect

Cause: Outbound HTTPS/WebSocket connections are blocked, or the registration token expired.

Fix:

1. Verify outbound HTTPS (port 443) is allowed in the server’s firewall
2. Test connectivity: curl -I https://api.reoclo.com
3. Generate a new registration token from the dashboard if the old one expired
4. Check runner logs: journalctl -u reoclo-runner -n 50

For more details, see Runner Servers.

Server Shows UNREACHABLE

Cause: The runner agent stopped or disconnected. Network interruption, service crash, or server reboot.

Fix:

1. Check if the service is running: systemctl status reoclo-runner
2. Restart the service: sudo systemctl restart reoclo-runner
3. Check logs for errors: journalctl -u reoclo-runner -f

Install Command Fails

Cause: curl isn’t installed, or the download failed due to network issues.

Fix:

1. Install curl: sudo apt install -y curl
2. Verify internet connectivity: curl -I https://get.reoclo.com
3. Retry the install command. If the token expired, generate a new one from the dashboard

Permission Denied (Docker) on Runner

Cause: The user running the Runner agent doesn’t have Docker permissions.

Fix:

1. Add the user to the Docker group: sudo usermod -aG docker $USER
2. Log out and back in for the change to take effect
3. Restart the runner service: sudo systemctl restart reoclo-runner

Deployment Issues

Build Fails

Cause: Dockerfile errors, missing dependencies in the build context, or insufficient disk space on the target server.

Fix:

1. Check the deployment logs in the dashboard for specific build errors
2. Test the Dockerfile locally: docker build -t test .
3. Verify disk space on the server: df -h
4. Ensure all required files are committed to the repository

For more details, see Deployments Overview.

Health Check Fails After Deploy

Cause: The app isn’t listening on the configured port, the health check path is wrong, or the app crashes on startup.

Fix:

1. Verify the app listens on the port specified in the application settings
2. Check the health check path matches your app’s endpoint (default: /)
3. Review container logs on the server: docker logs <container-name>
4. Test the health check manually: curl http://localhost:<port>/<health-path>

See Deployment Configuration for health check setup.

Deployment Stuck in PENDING

Cause: The deployment hasn’t started processing yet. This can happen during high load.

Fix:

1. Wait a few minutes. Deployments are processed in order
2. If the issue persists after 5 minutes, cancel and retry the deployment from the dashboard
3. Contact support if deployments consistently stall

Rollback Triggered Automatically

Cause: The health check failed after deployment, so Reoclo automatically reverted to the previous container.

Fix:

1. Check the deployment logs for health check errors
2. Common causes: wrong port, missing environment variables, app crash on startup
3. Fix the issue and redeploy

Environment Variables Not Applied

Cause: Environment variables weren’t saved before deployment, or the deployment used a stale configuration.

Fix:

1. Go to the application settings in the dashboard
2. Verify environment variables are saved (not just typed; click Save)
3. Redeploy the application

See Deployment Configuration for environment variable setup.

Domain Issues

Verification Failed

Cause: The TXT record isn’t found, DNS propagation is still in progress, or the record value is incorrect.

Fix:

1. Verify the TXT record exists:

   dig TXT _reoclo-verify.yourdomain.com +short

2. Wait 5-10 minutes for DNS propagation and retry
3. Ensure the record value matches exactly what’s shown in the dashboard

For more details, see Custom Domains.

DNS Not Resolving After Adding A/CNAME Record

Cause: The A or CNAME record isn’t pointing to the correct server IP, or hasn’t propagated yet.

Fix:

1. Check the current resolution: dig yourdomain.com +short
2. Verify the record points to your server’s IP address (check the server detail page)
3. Wait for DNS propagation (usually 5-60 minutes)

SSL Certificate Not Provisioning

Cause: DNS verification must complete first, or port 80 is blocked on the server.

Fix:

1. Complete domain verification first (see “Verification Failed” above)
2. Ensure port 80 is open: sudo ufw allow 80/tcp
3. Wait a few minutes after verification for automatic certificate provisioning

Domain Shows “Down” Uptime

Cause: The server is unreachable or the application isn’t responding.

Fix:

1. Check server health in the dashboard. If Unreachable, fix the server connection first
2. Verify the application is deployed and the container is running: docker ps
3. Test the app responds: curl http://localhost:<port>

GitHub Integration Issues

Webhook Not Received

Cause: The webhook URL is wrong, the GitHub App isn’t installed on the repository, or signature verification failed.

Fix:

1. Verify the GitHub App is installed on the repository (GitHub Settings → Integrations)
2. Confirm the webhook URL in GitHub App settings
3. Check webhook delivery logs in GitHub for errors or failed deliveries

For more details, see GitHub App Setup.

Auto-Deploy Not Triggering on Push

Cause: The wrong branch is configured in the application settings, or the GitHub App doesn’t have access to the repository.

Fix:

1. Verify the application’s branch setting matches the branch you’re pushing to
2. Confirm the GitHub App is installed and has access to the repository
3. Check recent webhook deliveries in GitHub for push events

Clone Fails During Deployment

Cause: The repository isn’t accessible to the GitHub App installation, or permissions changed.

Fix:

1. Verify the GitHub App has access to the repository (GitHub Settings → Integrations → Configure)
2. Check that the repository isn’t archived or deleted
3. If the issue persists, reinstall the GitHub App on the repository

General Issues

Can’t Log In

Cause: Wrong credentials, account suspended, or trying to access the wrong organization.

Fix:

1. Verify your email and password are correct
2. If you belong to multiple organizations, you’ll see an organization picker after login. Select the correct one
3. Contact your admin if your account may have been suspended or removed

User Can’t See Resources

Cause: Insufficient role permissions or logged into the wrong organization.

Fix:

1. Verify you’re in the correct organization (check the organization name in the sidebar)
2. Check your role with an admin. Viewers have read-only access, Developers can deploy, Managers can manage servers and apps
3. Switch organizations using the organization switcher if needed

See Team Management for role details.

Dashboard Shows Stale Data

Cause: Browser cache or outdated session.

Fix:

1. Hard refresh the page: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
2. Log out and log back in if the issue persists

Still Need Help?

If your issue isn’t covered here, check the detailed troubleshooting sections on each feature page:

• Runner Servers
• Custom Domains
• Status Pages

For additional support, contact us at [email protected].