Troubleshooting | Clusterz

What a failed build, a refused deploy or a silent push means, and what to do next.

You see	What it means and what to do
`the build failed` with a log	The log shows the failing step. A buildpack build that cannot find your app needs `root` set to its folder. A build command that is not an npm script needs a Dockerfile.
`build_command` is refused	A buildpack runs the scripts of your `package.json`, like `npm run build`. For any other command, use `build: dockerfile`.
`missing_required_env_vars`	The file marks a variable `required` and it has no value. Give it in the form, with `cluz up --set KEY=VALUE`, or with `cluz env set`.
`slug_in_use`	The app's address is taken. Choose another name for the app.
The release command failed	The deploy stopped before traffic moved and the running version is untouched. Read the release step's output, fix the command or the migration, and deploy again.
The health check timed out	The service did not answer `health_check` on `port`. Check that it listens on the port in the file, on all addresses (not only localhost), and that the path exists.
`the name ... is the platform's`	Only the service that keeps the app's own settings may be called `app`. No service can be called `release`, or a name its database's services use (`postgres`, `auth`, `rest`, `storage`, `realtime`). Rename it in `clusterz.yaml`.
`which clusterz.yaml does not name`	A file names every database the app has, and never removes one. Add the lines the message gives.
`a file cannot change the kind of a database` or `the version of a database`	A database keeps its kind and its Postgres version. Add a new database under another name for the new one, and move the data with your own dump.
`PostGIS runs on Postgres 16 or 18`	Give the database `version: 16` or `version: 18` beside `extensions: [postgis]`.
`the app has 2 databases; update cluz`	Your `cluz` is older than named databases. Update it with the command on the CLI page.
`type is needed when the app has more than one service`	A file of several services names each one's `type`: `web` for the one at the app's address, `api` for one the others call, `worker` for one with no port.
`field type not found in type projectfile.Service`	Your `cluz` is older than service types. Update it with the command on the CLI page.
A service's address does not answer	Its address is given a route only once it resolves to Clusterz. Until then the service is reached privately by the app's other services, and `from_service` gives that private address.
The file was not applied on a push	A push applies `clusterz.yaml` before it builds. If the file does not parse, the project keeps its settings and the build goes ahead. Run `cluz up --dry-run` to read the same message.
No deploy on a push	Check that `auto_deploy` is on, that the branch is the one the app builds, and, for GitLab and Bitbucket, that the push hook is registered on the app's page.