Troubleshooting
What to check when a build, deployment, domain or request doesn't do what you expect.
A push didn't start a deployment
- Is there a Skipped deployment for it? Then auto deploy is off for that environment.
- Do you use watch paths? The push has to change a matching file.
- Does the Teral GitHub App still have access to the repository? Check on GitHub under Settings → Applications.
- Was it a pull request from a fork? It waits in Awaiting approval. See GitHub.
The build fails
Open the deployment and read the build log from the top. The first lines show what Teral detected.
- Teral can't work out how to build the app: check the Root directory. It has to point at the folder with
package.json,go.mod,pyproject.tomland so on. - The wrong language or version: a leftover file, such as an old
requirements.txt, can win. Remove it, or pin the version. - A missing variable during the build: variables are only there for Dockerfile builds when you mount them.
- The build stops after 30 minutes: that's the limit. Speed it up, or build the image in your CI and deploy the image.
The deployment fails after the build
- The app crashes on start: read the runtime logs on the Logs page. Usually a variable is missing.
- The health check never passes: the path has to return
2xxwithin 5 seconds. Try it locally with the same port. - A limit was hit: the deployment page says which one. See Limits.
The URL shows an error page instead of your app
The page shows an error code. Each one has a page under Errors. The common ones:
| Code | Usually |
|---|---|
no_running_instances | The app crashes or is still starting. Check the runtime logs. |
service_unavailable | The app listens on the wrong port, or on localhost instead of 0.0.0.0. |
gateway_timeout | The app took too long to answer. |
deployment_offline | A preview deployment was stopped after an hour without traffic. Use Wake deployment. |
config_not_found | Teral doesn't know the hostname. Check the spelling, or whether the custom domain is verified. |
firewall_denied | One of your Firewall policies blocked the request. |
spend_limit_reached | The workspace reached its spend budget. |
A change doesn't show up
Deployments keep the settings, variables and policies they started with. After changing any of them, start a new deployment, for example with Redeploy.
The app restarts now and then
- Out of memory: the memory chart of the deployment climbs to the limit before each restart. Give it more memory, or find the leak.
- Failing health checks: an instance that fails its health check three times in a row is restarted. A check that depends on a database fails whenever the database is slow.
A custom domain stays unverified
- Check both DNS records with
dig, see Custom domains. - With Cloudflare, the record must be DNS only.
- After 24 hours the domain is marked failed. Fix the records and select Retry verification.
Still stuck?
Write to support@teral.dev or ask on Discord. Include the deployment ID, or the request ID from the error page or the X-Teral-Request-Id header.