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 cannot 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 are not 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 Does Not 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 is not 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

RunPod Pod Crash-Loops with “wget not found” and “run.sh: No such file or directory”

Cause: The persistent runner start command was spliced into a pod using a bare NVIDIA CUDA base image (for example, nvcr.io/nvidia/cuda:*-base). These images ship without curl, wget, or python3, so the previous start command could not download the runner binary, causing the pod to restart every ~17 seconds with output like:

bash: line 7: wget: command not found
bash: line 12: /opt/reoclo/run.sh: No such file or directory

Fix:

1. Upgrade to runner ≥ 1.27.8 (api ≥ 1.65.4, web ≥ 1.40.3). The updated start command automatically tries curl → wget → python3 (with a curl-style User-Agent, since some CDNs/WAFs block python-urllib’s default), then falls back to installing curl via apt-get, apk, dnf, or yum.
2. Re-apply the persistent runner from the dashboard Reinstall section for the affected pod so the pod picks up the updated start command.
3. Alternatively, pre-install curl or wget in your pod image to avoid the fallback entirely.

Permission Denied (Docker) on Runner

Cause: The user running the Runner agent does not 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 is not 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.

Docker Compose apps: Reoclo does not run the health check settings above for a Compose service. It waits for the selected compose service (or every service in the file, when no service is selected) to report running in docker compose ps, and healthy when the compose file defines a healthcheck:. When no service is selected, a one-shot service that exited with code 0 counts as complete, but the service named like the application must be running, and at least one service must be running. The error names the service and the state Docker reported, for example Compose service api did not become healthy: running (unhealthy) or Compose service api is not running: exited (code 1). The deploy log shows the last log lines of the service and the state of each service. A service that stays starting gets up to about two minutes before the deploy fails. If the message says Could not read compose service state, Reoclo could not read docker compose ps output; the containers are left in place for you to inspect.

Deployment Stuck in PENDING

Cause: The deployment has not 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 were not 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 is not 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 is shown in the dashboard

For more details, see Custom Domains.

DNS Not Resolving After Adding A/CNAME Record

Cause: The A or CNAME record is not pointing to the correct server IP, or has not 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 is not 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 is not 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 does not have access to the repository.

Fix:

1. Verify the application’s branch setting matches the branch you are 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 is not 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 is not archived or deleted
3. If the issue persists, reinstall the GitHub App on the repository

General Issues

Cannot 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 will see an organization picker after login. Select the correct one
3. Contact your admin if your account may have been suspended or removed

User Cannot See Resources

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

Fix:

1. Verify you are 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 is not covered here, check the detailed troubleshooting sections on each feature page:

• Runner Servers
• Custom Domains
• Status Pages

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