Docs · Account

Troubleshooting builds

Open the failed deploy on the app’s Deploys tab: its build log ends with the reason. Find that message below for what it means and what to change.

Detection

The build cannot tell how to build the app

can't tell how to build this app: no go.mod, composer.json, bun or npm lockfile, or index.html in its folder - set the build and output in the app's build settings

homeport looked in the app’s folder and found nothing it knows. Check the Root directory is the folder with your go.mod, package.json and lockfile, or composer.json; commit the lockfile (Yarn and pnpm lockfiles are not detected); or set the build yourself. See What homeport detects.

composer.json without composer.lock

composer.json without composer.lock: commit the lockfile, so the build installs what you tested

Run composer install locally and commit composer.lock.

rsc-kit

build: no .output/rsc-kit.json - rsc-kit 0.29.6+ writes .output/rsc-kit.json after its build; upgrade rsc-kit, or say what it makes in homeport.yaml (static: / build:)

homeport reads the marker rsc-kit writes after its build to know whether it made a static export or a server. Upgrade @rsc-kit/core to 0.29.6 or newer, or say what it makes in homeport.yaml: static: dist for an export, or build.command and build.artifact for a server. The same advice follows any other problem with the marker, such as .output/rsc-kit.json: '…' isn't one of package.json's scripts when the compile script it names is missing.

The build’s output

Output errors
Message	What to change
`build: no binary at server - did the build produce it?`	The build finished but left no binary where expected, and no static site in `build`, `dist` or `out`. Write the binary to `server`, or set `build.artifact` to where it is.
`build: no index.html in dist - is that the site's folder?`	A static site’s folder must have an `index.html` at its top. Point `static` (or the Output folder setting) at the folder your build writes.
`build: the site has a symlink (…) - homeport serves files, not links`	Copy the file instead of linking it in your build.
`the build didn't produce a Linux executable`	The binary is not a Linux program: build for Linux, not macOS or Windows.
`the binary is built for the wrong architecture`	Build for the architecture the app runs on, or let homeport build it.
`the binary is too large`	Make the binary smaller, for example by stripping symbols.

Running and the health check

Deploy errors
Message	What to change
`health check failed — reverted to …`	The new release did not answer `GET /` with a status below 400 within 30 seconds, so the previous one is still serving. Listen on `$PORT` and on `0.0.0.0`, not `localhost` or a fixed port. The Logs tab shows what the app printed.
`health check failed and there is no previous release to revert to`	The same, on a first deploy.
`release hook failed — deploy aborted`	Your `release` command exited with an error. Nothing changed: the previous release is still live.
`processes need an always-on app: this plan's apps sleep when idle`	Turn on Always on for the app (a paid plan), or remove `processes`.

homeport.yaml

homeport.yaml errors
Message	What to change
`homeport.yaml: a sandboxed release command is args to ./bin, run without a shell …`	Write `release` as arguments to your binary, with no `&&`, pipes or variables.
`homeport.yaml: run may only reference $PORT and $HOST, no other variables`	Read other variables from the environment in your code.
`homeport.yaml: at most 4 processes`	Combine or remove processes.
`build.image needs a build.command: what to run in it`	Add `build.command`.

Limits and time

Limit errors
Message	What it means
`this month's build minutes are used up`	Free’s 120 build minutes for the month are spent. What is live keeps serving; builds start again next month. See Free and its caps.
`build: timed out after …s`	The install and build together ran past the time limit. Look at the log for the step that hung.
`build: the build failed (exit …)`	Your install or build command failed. The lines above it in the log say why.

A build runs with up to 4 GB of memory and 2 CPU cores, whatever the app’s own size. You can cancel a build from its page; pushing again to the same branch replaces a build that has not started yet.