Troubleshooting
Fixes for the problems you're most likely to actually hit while deploying and running apps on Raklane.
Practical, ordered checklists for the failure modes you're most likely to hit. Start with Logs & Status if you haven't already — most of these start there.
My deploy failed
- Check the failure reason on your App's Status page — it tells you whether the build failed or a running container failed its health check. These need different fixes.
- Build failed — check your App's Logs, and confirm your repository has something Cloud Native Buildpacks can actually detect at its root (a
package.json,requirements.txt,go.mod, etc.) or aDockerfile. A repo with neither at the root fails to build. For a Dockerfile build, the error names the step that failed; if your Dockerfile isn't at the root, set its path in Settings → Build. - Health check failed — your container started but never became healthy in time. Common causes: your app doesn't actually listen on the port Raklane detected or was told (double-check
container_port), it crashes on startup (check Logs for a stack trace), or it takes longer to become ready than the health check's timeout allows. - Whatever was running before a failed deploy is left completely untouched — a failed deploy never takes your app offline.
My app deployed but I can't reach it
- Give it a few seconds — routing updates run on a short interval, so a brand-new deploy or domain can take a moment to become reachable after showing
active. - Confirm you're using the URL from the App's Status page, not a guess.
- If you're using a custom domain, confirm it shows
verifiedon the Domains page first — see Custom Domains.
My private repo won't build
The most common cause is a missing or expired access token. Check that your App's source references a valid secret with read access to the repository — see Secrets → Private repositories. A token that's since been revoked or expired fails the same way a missing one does.
My GitHub push isn't triggering a deploy
- Open your App's Settings page. The Automatic checks panel shows what Raklane last saw on your branch, and why it didn't deploy if something is wrong (for example, an expired access token, or an App that hasn't had its first deploy yet).
- Confirm the App's deploy mode is Auto Deploy — in the manual modes, pushes never deploy on their own.
- Confirm you pushed to the branch your App's source is actually configured to build from — pushes to other branches are ignored.
- Check the webhook's Recent Deliveries tab in your GitHub repository settings. A 401 response means the secret on GitHub doesn't match the one saved in Raklane — generate a new secret on the App's Settings page and paste it into GitHub. Even then, the automatic checks still deploy the push, just not instantly.
- See Auto-Deploy & Deploy Modes for the full setup.
My environment variable change didn't take effect
Environment variables are snapshotted into a container at the moment it starts — they aren't live-reloaded. Trigger a redeploy after changing one; see Environment Variables.
My custom domain won't verify
- Confirm the DNS record actually resolves to the address Raklane expects — the Domains page shows what it's currently resolving to when verification fails, which is the fastest way to tell a DNS mistake from a propagation delay.
- DNS changes can take time to propagate globally; if you just created the record, wait and check again before assuming it's wrong.
- For a Bring Your Own Compute app, the domain must point at that server's IP, not Raklane's shared infrastructure.
HTTPS isn't working on my custom domain
Certificate issuance only starts after the domain finishes DNS verification, and only on the first real request that arrives for it. If it's verified but HTTPS still isn't working, send an actual request to the hostname over HTTPS to trigger issuance, and confirm port 443 (and 80, used during issuance) is reachable.
I can't pause or delete something
- Deleting an app requires it to be paused first — pause it, then delete it.
- Deleting a project requires every app inside it to be deleted first.
These are safety rails, not bugs — see Managing Your App.
I can't invite a teammate
Most commonly, your Organization is out of seats — pending invites count against the limit the same as active members. Check your Organization's Members page, and see Teams & Organizations → Seats. Inviting also requires at least the Admin role.
My deploy is stuck on "waiting for server"
Raklane is starting a server with room for your app; this normally takes a few minutes and continues on its own. If it eventually fails with a message about the maximum number of servers or a replica being too large, lower the app's CPU/memory requests (Resources page) and redeploy, or contact Raklane support at hi@raklane.com.
Problems with my own server (BYOC)
See BYOC Troubleshooting — it covers servers stuck on Pending or Offline, apps that don't load, HTTPS and domain problems, image pull failures, and paused deploys. The most common cause by far is ports 80/443 blocked by a cloud provider's firewall, even when the OS firewall looks fine.
My database is stuck in "provisioning" or failed
A single transient hiccup (e.g. the engine needing a moment after starting before it accepts connections) is normal and retried automatically — it isn't a dead end. If it stays stuck or shows failed with a reason for more than a minute or two, check that reason on the Databases page first; for a dedicated-hosting database, also check your wallet has enough balance, since a lapsed subscription suspends the database (its data is kept, and starting it again after renewing brings it back).
Still stuck?
Check the FAQ, or email Raklane support at hi@raklane.com.