Key idea
When a build fails, read its log from the top and fix the first error, not the last. If the build finished and the service still failed, the problem is in starting the app, and the answer is in the deploy and runtime logs instead.
Where build logs live
A service built from a repository has a Builds tab on its service page. Services deployed from an image don't build, so they don't have one.
The left side lists every build, newest first, with its status, when it started, and its build method: Native for a runtime build, Docker for a Dockerfile build. Select a build and its output appears on the right, streaming while it runs. The toolbar has search, Copy all and Download .log.
From the terminal:
csph logs my-app --kind build
csph looks the service up in your default project and environment (lesson 5.1.1). --kind deploy shows the rollout steps, and --kind runtime, the default, shows your app's own output.
Build statuses
- Queued: waiting for a builder.
- Building: fetching your code and building the image; output is streaming.
- Built: the image is ready.
- Deploying: the new image is rolling out.
- Running: the rollout finished; this build is serving.
- Failed: the build or its rollout stopped with an error. A build running longer than two hours is stopped and marked Failed.
- Canceling, Canceled: someone stopped it, or a newer build replaced it. A running build has a Cancel button.
The service's own statuses are in the table in lesson 5.1.3.
Reading a failed build
- Read the message at the top. A failed build shows a short failure message above its output. Sometimes that's all you need.
- Find the first error. One problem usually causes a cascade: a missing package, then an import error, then a failed compile. Search for
errorand start from the earliest match. - Note which step it stopped in. The output runs through fetching your code, installing dependencies, your build command, then pushing the image. Where it stops tells you what to fix.
The usual causes
- Can't find
package.json,requirements.txtorgo.mod: the file isn't at the repository root. For an app in a subfolder, see lesson 5.3.5. - A dependency won't install: a typo, a private package, or a version that doesn't support the runtime version you picked.
- Compile or type errors: the code doesn't build. Run the same build command on your machine.
- A value is missing during the build: only variables named
NEXT_PUBLIC_…orVITE_…reach a build, and secrets never do (Module 4).
If a build fails in a way that doesn't match your code, a stale cache is possible. Choose Redeploy, then Build & deploy, and tick Clear build cache.
Build failed, or deploy failed?
If the build shows Built or reached Deploying, the image is fine. The trouble is starting it: a wrong port, a start command that doesn't match your app, a crash on start. Look in the deploy and runtime logs, as in lesson 5.1.3.
On a repository-built service, the Logs tab has a View build logs link that jumps to the build.
Check yourself