Build troubleshooting
Find the failing stage, read the logs, and fix common build and deploy problems.
Where to start
- Check the project status on the project page.
- Open the Pipelines tab and open the latest pipeline.
- Find the failing stage: Clone, Build, Push, or Deploy.
- Read that stage's logs.
- Use Ask AI if you need the error explained.
Common problems
| Symptom | Likely cause | Fix |
|---|---|---|
| Build succeeds but the site does not load | The app listens on a different port | Match the port in Settings → General to the app's real port |
| Missing Dockerfile or main file | Wrong file path | Fix the path in Settings → General |
| npm package 404 | The package is not in the current registry | Change the npm registry in Build & CD and rebuild |
| npm registry timeout | Temporary registry problem | Choose another registry or retry the build |
| 403 while pulling an image | Temporary Docker registry problem | Click Retry once; if it repeats, contact support |
| Out of memory or resources during build | Heavy build or too many dependencies | Remove unnecessary dependencies; if it continues, open a ticket |
| Environment variable error | Double quotes or a trailing backslash | Fix the value in Envs |
| Insufficient balance status | Low account balance | Top up the account |
Retry, Trigger, or Rollback?
- Retry: runs the same pipeline and commit again. Good for temporary failures.
- Trigger Pipeline: creates a new pipeline with the latest code.
- Rollback: redeploys the code from an earlier pipeline. Variables and settings are not restored.
Clone stage failure
If fetching code from the repository times out or fails:
- Check the Git account connection.
- Check repository access and the branch name.
- Click Retry once.
- If it repeats, contact support.
Build stage failure
- Read the failing package or command in the log.
- Fix dependencies or versions in the repository and push.
- For Node projects, check npm Registry.
- If the error is network or registry related and changing the registry does not help, open a ticket.
Push or Deploy stage failure
These failures are usually infrastructure related:
- Click Retry once.
- If it repeats, contact support with the pipeline ID and the error text.
The app runs but returns errors
- Check the Logs tab.
- Use the Console to inspect the app and its configuration.
- Verify the port and Readiness probe.
- Check environment variables and the database connection.
When contacting support
Prepare:
- Project name and ID
- Pipeline ID or time
- The failing stage
- The error text or relevant log excerpt
Do not include passwords or sensitive variable values in the ticket.