Common Issues

Common Issues#

Here are the most common problems developers run into and how to fix them.

Build fails#

If your build fails, the first step is always to check the build logs.

runix logs my-service --build

App crashes on startup#

If your app builds successfully but crashes immediately after starting, check these common causes:

• PORT environment variable — Your app must listen on the PORT environment variable, not a hardcoded port. Runix injects this at runtime.
• Missing environment variables — Check that all required env vars are set in the dashboard or CLI.
• Health check failing — Runix checks that your service responds on the configured port. Make sure your app is ready to accept connections.
• Database not available — If your app needs a database, make sure it is deployed and the connection string is set in env vars.

// Correct: use the PORT env var
const port = process.env.PORT || 3000;
app.listen(port, '0.0.0.0', () => {
  console.log(`Server running on port ${port}`);
});

Custom domain not working#

If your custom domain is not routing to your service:

1. 1.Verify your DNS: Your CNAME record must point to runixcloud.dev (not your deployment's subdomain)
2. 2.Wait for DNS propagation: DNS changes can take up to 48 hours. Most resolve within an hour.
3. 3.Run domain verification: Go to your deployment's domain settings and click "Verify" to check the DNS record.
4. 4.Check your plan: Custom domains require the Starter plan or above.

Deployment stuck in "building"#

If your deployment appears stuck in the building state for more than 10 minutes:

• Check build logs — The build may still be running (large dependency installs can take a while)
• Large Docker images — If your project has many dependencies, the initial build takes longer. Subsequent builds use the cache.
• Build timeout — Builds that exceed 15 minutes are automatically cancelled. Optimize your dependencies or upgrade your plan for more build resources.
• Trigger a redeploy — If the build seems stalled, try redeploying from the dashboard or CLI.

502 Bad Gateway#

A 502 error means the proxy cannot reach your container. This usually happens when:

• Your service is still starting up — Wait a few seconds and refresh.
• Your app crashed — Check the runtime logs for errors.
• Your app is not listening on the correct port — Make sure it uses the PORT environment variable.
• Your service ran out of memory — Check if you see OOM errors in the logs and consider upgrading your plan.

# Check runtime logs for errors
runix logs my-service

Environment variables not loading#

If your app is not picking up environment variable changes:

• Redeploy after changes — Environment variables are injected when the container starts. You must redeploy for changes to take effect.
• Check the variable names — Keys are case-sensitive. DATABASE_URL is not the same as database_url.
• Verify in the dashboard — Open your deployment settings and confirm the variables are set correctly.