Launch offerYour first 90 days of BYOC are free for one server — connect a server you already rent. Until January 15, 2027.Claim it →

BYOC Troubleshooting

Fixes for BYOC servers stuck on Pending, apps that won't load, HTTPS that won't issue, failing image pulls, and more.

Most BYOC problems come down to one of three things: a firewall (usually your cloud provider's, not the OS's), DNS that doesn't point at your server yet, or the server not being able to reach Raklane outbound. Work through the section that matches what you're seeing.

Two commands on your server answer most questions:

sudo systemctl status raklane-agent     # is the agent running?
sudo journalctl -u raklane-agent -f     # what is it doing / complaining about?

For more detail, set RAKLANE_LOG_LEVEL=debug and RAKLANE_LOG_FORMAT=text in /etc/default/raklane-agent and restart the agent. See BYOC Agent Configuration.

The agent won't start after I changed its settings

  • Check the file for typos: sudo cat /etc/default/raklane-agent. Each line must be KEY=VALUE, with no spaces around =.
  • Did you move RAKLANE_AGENT_STATE_DIR? Without its files, the agent tries to enroll again and fails, because the token has already been used. Move the files back, or point the setting back at the old directory.
  • Did a duration setting stop having an effect? Values like 15s or 1h that can't be parsed silently fall back to the default.
  • Did you re-run the install command? It rewrites the settings file and drops your custom lines. Add them back.

The server is stuck on Pending

The server registered but never enrolled.

  1. Did the install command finish? Re-run it — it's safe to run again — and watch for errors.
  2. Was the token already used, or replaced? Tokens work once, and regenerating one invalidates the previous one. Use Regenerate token from the server's menu and run the new command.
  3. Can the server reach Raklane? From the server, run curl -I against the Raklane URL in the install command. If that fails, check outbound firewall rules, DNS resolution on the server, or a corporate proxy.
  4. Can the server reach the agent connection port? Enrollment can succeed but the server never turns Healthy if the agent connection port (8443 by default) is blocked outbound. The agent logs show connection errors in this case.

The server went Offline

The agent lost its connection to Raklane.

  • Is the server running? Check your provider's console, then try ssh.
  • Is the agent running? sudo systemctl status raklane-agent. If it's stopped, sudo systemctl restart raklane-agent.
  • Did something change on the network? A new firewall rule, a changed DNS resolver, or a provider-side outage can all block the outbound connection.

The agent reconnects automatically once it can. Your apps usually keep serving visitors while the server shows Offline — "unreachable" in the dashboard means Raklane can't currently confirm their state, not that they've stopped.

The server is Healthy, but my app's URL doesn't load

This is almost always ports 80/443 being blocked in front of the server.

Start with Raklane's own check. Every few minutes, Raklane tries ports 80 and 443 on your server from the internet, and checks that your server's Caddy answers, not just that the port is open. If visitors can't get through, a warning appears on the Clusters page and on the app's own page, saying what was found and what to do:

What it showsWhat it usually means
Both ports closedThe server has no public IP of its own: it sits behind your provider's NAT. See step 6.
Both ports time outA firewall in front of the server, or NAT. See steps 1 and 6.
Both ports refusedThe server answers, but Caddy isn't running on it. Check sudo systemctl status caddy.
Another server answersSomething else (nginx, Apache, another Caddy) is using the port. See step 3.
Private addressThe server's IP is a LAN or local address that no visitor on the internet can reach. Set its External host if the provider forwards a public IP to it.

On the server itself, the agent also checks at every start whether the public IP it reports is on any of the server's network interfaces. If it isn't, journalctl -u raklane-agent | grep NAT shows a message saying the server is behind NAT.

Then work through the usual causes:

  1. Open 80 and 443 in your cloud provider's firewall (AWS Security Group, GCP firewall rule, DigitalOcean/Hetzner/Vultr cloud firewall), to 0.0.0.0/0. The install command only opened them in the OS firewall.
  2. Check the OS firewall too, if you use something other than ufw (iptables, nftables, firewalld).
  3. Check nothing else is using 80/443. Another web server (nginx, Apache, a separate Caddy) on the same server prevents Raklane's Caddy from serving. sudo ss -ltnp | grep -E ':80 |:443 ' shows what's listening.
  4. Confirm the deploy is actually active on the app's overview page, and that you're using the exact URL shown there.
  5. Give routing a few seconds after a deploy goes active.
  6. Is the public IP shared with other servers? If your provider only forwards a few ports to your server (a Port Forwarding page, SSH on a port other than 22), ports 80/443 never reach it and this can't be fixed from the server. This kind of VPS isn't supported — see Shared-IP VPS are not supported, which also shows how to check your server.

HTTPS doesn't work / certificate errors

  • Is the domain verified? For a custom domain, the Domains page must show verified first. No certificate is requested before that.
  • Does DNS point at the server? dig +short app.example.com should return your server's public IP. If it returns a CDN's IP (for example, Cloudflare with proxying on), switch to DNS-only.
  • Is port 80 reachable from the internet? The certificate authority verifies over port 80, even though your app is served on 443.
  • Send a real HTTPS request. Certificates are issued on the first request for a hostname; open the URL in a browser and give it a few seconds.
  • Is the server's IP private? Servers with a private/LAN IP are served over plain HTTP only — this is expected, since no certificate authority can reach them.
  • Hitting certificate authority rate limits? Repeatedly destroying and recreating a server, or changing many hostnames in a short time, can temporarily hit the certificate authority's limits. Wait and try again later.

My custom domain stays Pending

  • The A record must point at your server's IP, not at Raklane's. The Domains page shows what the hostname currently resolves to.
  • DNS changes can take time to propagate. Raklane keeps checking automatically and never gives up — if the record is right, it will verify.
  • A proxying CDN in front of the domain resolves to the CDN's IP, which fails verification. Use DNS-only mode.

Deploy fails pulling the image

  • server gave HTTP response to HTTPS client — the image registry runs over plain HTTP (development setups). Re-run the install command with --insecure-registry=HOST:PORT added (ask Raklane support at hi@raklane.com for the value), then redeploy.
  • Authentication or "not found" errors — the server may not be able to authenticate to the registry. Contact Raklane support at hi@raklane.com.
  • no space left on device — free up disk on the server (sudo docker system prune removes unused images and stopped containers), then redeploy.
  • Timeouts — check the server can reach the registry over HTTPS outbound.

A deploy that already failed doesn't retry on its own after you fix the cause — click Redeploy.

Deploy is rejected for capacity

The app's CPU/memory requests don't fit in what's left on the server. Either lower the app's requests (Resources page), move or delete other apps on that server, or use a bigger server. Remember that requests count even when the app is idle — that's what reserves the room.

Deploys to my servers are paused

Your BYOC management fee has been unpaid for longer than the grace period. Everything already running is fine. Top up your wallet from Billing — once the amount owed is collected, deploys work again. See BYOC Billing.

My app can't connect to its database

  • Are they on the same server? A local database is reachable only by apps on the same BYOC server. If they're on different servers, either move the app, or make the database external and connect using its external address.
  • External database not reachable? If its external address is your server's own IP, the database port must be open in both the server's and your cloud provider's firewall. If the address shown is a private IP, set the server's External host (Clusters → Edit).
  • Wrong password? The password is only shown at creation. If it's lost, the database has to be recreated.

Apps show "unreachable"

Raklane can't currently confirm those apps' state, usually because the server is Offline or Docker on the server isn't responding. Check sudo systemctl status docker and the agent's status. Once the server is back, Raklane re-verifies and the apps return to active without a redeploy.

Still stuck?

Collect the output of sudo journalctl -u raklane-agent --since "1 hour ago" and the result of Check connection, and email them to Raklane support at hi@raklane.com. See also the general Troubleshooting page.