Troubleshooting

Start with the failed deployment’s page: the message at the top says what went wrong, and the log shows the details. Below are the messages you’re most likely to see.

Build failures

“Root directory ‘…’ does not exist in the repository”

The Root directory setting points to a folder that isn’t on the deployed branch. Check its spelling and letter case (Apps/Web isn’t apps/web), and that the folder is committed on that branch. Fix it under Source and build → Edit settings, then Deploy.

“No Dockerfile in ‘…’”

The build type is Dockerfile, but there’s no file named exactly Dockerfile in the app’s folder. Add one, change the root directory, or choose another build type.

“Build failed (exit code …)”

Your install or build command failed. Scroll up in the build log to the first error. The usual causes:

• Lockfile out of date: npm ci and --frozen-lockfile refuse to install when package.json and the lockfile disagree. Run the install locally, commit the updated lockfile, and push.
• A script works on your machine but not here: builds start from a clean copy of your repository, so a file that’s ignored by git (such as .env) isn’t there. Use environment variables instead.
• Out of memory: large builds can exceed 3 GB. For Node.js tools, try NODE_OPTIONS=--max-old-space-size=2048 as a variable, or reduce what the build does.

“Couldn’t fetch the source code”

Shiplon couldn’t fetch the commit from GitHub. Check the repository is still included in the GitHub App’s repository access, and the app isn’t suspended.

“Build timed out after 15 minutes”

Builds are limited to 15 minutes. Check for a step waiting for input, or a very slow download; speed up the build, or move heavy work out of it.

Deploy failures

“The image runs as root…”

Shiplon only runs apps as a non-root user. Add a numeric user to your Dockerfile, for example USER 10001, making sure that user can read your files and write where it needs to. See Dockerfile.

“The image sets its user by name (”…“)”

Kubernetes can’t verify that a named user isn’t root. Use the numeric ID instead, for example USER 1000 instead of USER node.

“The new version didn’t start: the app keeps exiting (exit code …)”

Your app starts and then stops. The message includes the last output your app printed; that’s usually the error. Common causes:

• a missing environment variable, for example the app throws when DATABASE_URL isn’t set;
• the start command is wrong, or the build output is missing (for example next start without next build);
• the app can’t reach a database that only accepts connections from certain IP addresses.

“The new version wasn’t ready within 5 minutes”

The app started, but never accepted connections on its port. Check that it:

• listens on 0.0.0.0, not localhost or 127.0.0.1;
• listens on the app’s Port setting, or better, on process.env.PORT.

If the message mentions a health-check path, that path never answered successfully; see the next message.

“GET /… answered HTTP 4xx inside the pod for over a minute”

The Health check path doesn’t answer 2xx or 3xx, often because it needs a login or doesn’t exist (404). Point it at a public endpoint such as /healthz, or clear it to use the default check.

“Health check failed: …”

The app started, but its address didn’t answer successfully. Without a health check path, any answer below 500 passes, so this usually means the home page returns a 5xx server error. Check the runtime logs for the error.

In all of these cases the previous version kept serving; your visitors weren’t affected.

Other problems

My push didn’t deploy

• Check Deploy automatically on push is on for the app.
• Check you pushed to the app’s branch: pushes to other branches are ignored.
• On Integrations → GitHub, check Recent events from GitHub shows the push. If it doesn’t, the repository may not be included in the app’s repository access.

The site works on its shiplon.app address but not on my domain

See the domain’s status under Domains and what each status means. DNS changes can take a few minutes, sometimes longer, to reach everyone.

My changes to settings or variables didn’t take effect

Settings and variable changes apply from the next deployment. Click Deploy.

Files my app wrote have disappeared

An app’s disk is temporary and is reset on every restart and deployment. Keep data in a database or external storage.

Still stuck?

Email hello@shiplon.com with your organization and app name, and the failed deployment’s page address. Don’t send passwords or variable values.