Troubleshooting

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

1. 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.
2. 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.). A repo with no recognizable project file at the root fails to build.
3. 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.
4. 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 — the default subdomain format depends on your Raklane installation's configuration.
• If you're using a custom domain, confirm it shows verified on 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

• Confirm the webhook secret configured on your App's source matches exactly what you entered in GitHub's webhook settings — a mismatch is silently rejected, and this is the single most common cause.
• 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 to see whether GitHub even attempted delivery, and what response it got back.
• Confirm the App's deploy mode is Auto Deploy — in the manual modes, pushes never deploy on their own.
• 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 your Raklane installation 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 whoever operates your Raklane installation.

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 reach out to whoever administers your Raklane installation.