If something fails
The most common errors when deploying on Olimpia, what they mean, and how to fix them.
Start with the deploy that failed: open it in Deploys and read the error and the end of the build log.
By error type
| Error | What it means | What to do |
|---|---|---|
source_failed |
The code could not be fetched. | GitHub: check that the branch exists and that the GitHub App still has access to the repo. Uploaded code: the URL expired or the upload did not finish. Upload it again. |
build_failed |
Railpack or your Dockerfile failed. |
Read the build log. See Build failures. |
import_failed |
The built image could not be saved. | This is a platform problem. Deploy again. If it happens again, contact us. |
release_failed |
The container did not start. | The process almost always exits right after it starts. Check the app’s Logs. |
internal_error |
Platform error. | Deploy again once. |
timeout |
The build took longer than 30 minutes. | Look for slow steps or use a multi-stage Dockerfile with caching. |
Build failures
It can't find how to start the app
Add a start script, a Procfile, or a railpack.json with startCommand. In monorepos, check the Root directory. See Builds.
The lockfile doesn't match
npm ci, pnpm install --frozen-lockfile, and bun install --frozen-lockfile fail if the lockfile is out of sync with package.json. Regenerate it on your machine, commit it, and deploy.
TypeScript or lint errors
The build runs in production mode. Fix the errors in your code.
A variable is missing during the build
Variables like NEXT_PUBLIC_*, or code that reads variables during the build, must be set before the build runs. Add the variable in Variables and deploy.
The build runs out of memory
Reduce build parallelism or switch to a multi-stage Dockerfile.
Native modules (sharp, bcrypt, canvas)
These usually work with Railpack. If they don’t, use a Dockerfile based on a full Debian image.
The app is Online but doesn’t respond
Online only means the container started. Try the URL and check the Logs.
Bad gateway or no response
Your app listens on localhost or on a fixed port. Make it listen on 0.0.0.0 and on $PORT, or set the app’s actual Port and deploy.
It keeps restarting
A variable or the database is missing. Check Variables and make sure the database is connected.
It can't connect to the database
You are using localhost or the public URL instead of the internal one. Use DATABASE_URL exactly as Olimpia sets it. If the database is new, run your migrations on startup.
404 when reloading a route in a SPA
Your server must return index.html for routes that are not files.
I see an Olimpia page instead of my app
This page appears when the subdomain has no online deploy: the app hasn’t finished its first deploy yet, doesn’t exist, or changed its subdomain. Check the current address in Settings → Domains.
Custom domain doesn’t activate
The console shows which records it expects and which it finds. Without the _olimpia TXT record, which proves the domain is yours, the domain does not move forward. DNS changes can take a few minutes to propagate. A CNAME at the root of the domain needs CNAME flattening or ALIAS. See Domains.
Still stuck?
Email us at [email protected] with the name of the app and the deploy.