Builds
Find the message a failed, stuck or undeployed build shows, and fix its cause: Dockerfile and Railpack errors, clone failures, nebula.toml problems, agent versions and build limits.
A build clones a service's repository at one commit, chooses the Dockerfile or Railpack, builds in the cluster and pushes the image. A failed build reads Build failed in the service's Deployments tab with the message below, and its log is grouped as Clone, Build and Push. A cluster runs two builds at once and a service runs one, so other builds read Queued. Retry rebuilds the same commit, never the current branch head.
Failed builds
No Dockerfile was found at the configured path. Add one to the repository, or fix the path in the service's settings.
Cause: The build engine could not read the Dockerfile at the path the build asked for.
Fix: Add the file, or correct Dockerfile and Build context in the service's Source settings. A dockerfile key in the [build] section of nebula.toml overrides the Dockerfile setting. See nebula.toml.
Verify: Select Retry. The build passes the Build phase.
no Dockerfile at <path> on <branch> and nothing recognizable to build automatically; add a Dockerfile, or add a package.json (or go.mod/requirements.txt/Gemfile/composer.json/Cargo.toml) for a project NebulaCtrl can detect
Cause: The build engine is Detect automatically, the path has no Dockerfile, and project detection found no project it can build with Railpack. The build log names what detection found.
Fix: Add a Dockerfile or one of the listed project files, or correct the path. See Build without a Dockerfile.
Verify: The new build's log reads building with Railpack or Dockerfile found at <path>.
The step `<command>` failed with exit code <n>; the build log above shows its output.
Cause: A RUN step of the Dockerfile exited with a non-zero code.
Fix: Read the log in the Build phase, fix the command or its inputs, and push.
Verify: The new build passes the Build phase.
The build's base image could not be pulled: access was denied. Check the image name and any registry credentials.
Cause: A FROM image could not be resolved. The other form reads The build's base image could not be pulled: it was not found. Check the image name and tag in the Dockerfile.
Fix: Correct the image name and tag in the Dockerfile, or add registry credentials. See Git providers and registries.
Verify: Select Retry. The build passes the Build phase.
The repository could not be cloned: the git connection could not authenticate. Reconnect it under Git connections.
Cause: The clone failed with could not read username, authentication required, authentication failed, repository not found or failed to fetch remote.
Fix: Reconnect the provider under Settings > Integrations, in Source control, and confirm the connection can read the repository.
Verify: Select Retry. The Clone phase succeeds.
The built image could not be pushed to <registry>. This is a cluster problem, not your code: check that the cluster's build registry is running, or that an external registry is configured and reachable.
Cause: The Push phase failed. The message names the registry host.
Fix: Ask a cluster operator to check that the build registry runs, or that the external registry is reachable.
Verify: Select Retry. The Push phase succeeds.
The build ran out of disk space on its node. Retry once the node has freed space, or ask an operator to expand it.
Cause: The build node reported no space left on device.
Fix: Free or add disk on the node, then select Retry.
Verify: The build completes the Build phase.
build exceeded 30 minutes
Cause: A build ran for more than 30 minutes and was cancelled on the cluster. A build stopped by a deadline reads The build ran out of time and was stopped.
Fix: Find the slow step in the log, reduce the build context, and select Retry.
Verify: The build finishes in under 30 minutes.
The build failed: the build pod was never scheduled onto a node.
Cause: The cluster could not place the build pod. When the build container cannot start, the message reads The build failed: the build image could not be pulled., or quotes the pull reason.
Fix: Check the cluster's nodes and agent. See Clusters and agents.
Verify: Select Retry. The build moves past Clone.
The build failed: <last line of the build log>
Cause: No known failure pattern matched, so the message ends with the last line of the log.
Fix: Read the log above that line and fix the named problem.
Verify: Select Retry or push; the build passes.
nebula.toml is invalid: <path> (line <n>): <problem>
Cause: The repository's nebula.toml does not parse, or does not resolve for this environment. Each problem names its key, with a line number when known. The build log shows nebula.toml is invalid; fix the problems below and push again.
Fix: Fix every listed problem and push. See nebula.toml.
Verify: The new build's log shows a nebula.toml: summary line.
couldn't read nebula.toml at <commit> from <provider>: <error>; nothing was built — retry the build
Cause: The provider failed while the control plane read the file. The build never builds without a file it was told to read.
Fix: Select Retry. If it fails again, check the git connection.
Verify: The build log shows the nebula.toml read.
couldn't decide a build engine: <step>: <error>; nothing was built — retry the build
Cause: A control plane lookup failed before the build started. The step is reload build, cluster capabilities, nebula.toml build settings or check for a Dockerfile at <path>. couldn't detect a build engine is the detection form.
Fix: Select Retry. If the step is check for a Dockerfile, confirm the git connection reads the repository.
Verify: The build leaves Queued and starts.
nebula.toml (or this service's build settings) says builder = "dockerfile", but no Dockerfile exists at <path> at <commit>; add one, or remove the override so NebulaCtrl can detect a build engine automatically
Cause: Build engine is Dockerfile (or [build] builder says so) and the file is missing.
Fix: Add the Dockerfile, or set Build engine to Detect automatically.
Verify: The new build's log shows the engine decision.
Railpack could not prepare a build plan for this repository; its own output above says why
Cause: Build engine is Railpack and its plan step failed. In an automatic build the message reads no Dockerfile at <path>, and Railpack could not build this repository automatically; add a Dockerfile, or a package.json, go.mod, requirements.txt, Gemfile, composer.json or Cargo.toml.
Fix: Read Railpack's output in the log and fix the project, or add a Dockerfile.
Verify: The new build passes the Build phase.
nebula.toml sets a build target or build args, but this cluster's agent doesn't support them yet: re-run the installer to update the agent, then build again
Cause: The cluster's agent predates build targets and build arguments. A service Build target gives this service builds the Dockerfile stage "<stage>", but <cluster>'s <agent> doesn't support build targets yet.
Fix: Update the agent, or re-apply its manifest on an old cluster. See Agent updates.
Verify: Select Retry. The build proceeds.
this cluster's build policy, Build CRD or agent predates Railpack builds
Cause: The message continues with the advice to re-apply the agent manifest. The cluster's build policy, Build definition or agent cannot run Railpack builds.
Fix: Re-apply the manifest. See Agent updates.
Verify: Select Retry. The build starts.
<cluster>'s agent (<version>) can't choose between Dockerfile and Railpack after cloning, and NebulaCtrl can't read this repository's files from its host
Cause: The repository host does not allow reading files and the agent cannot decide the engine after cloning.
Fix: Update the agent in the Agent section of the cluster, or set Build engine to Dockerfile or Railpack.
Verify: Select Retry. The build starts.
the image was built and pushed, but the cluster's agent did not report its digest, so no release was created and nothing was deployed. Update the cluster's agent, then retry this build.
Cause: The build pushed an image, but a release needs its digest.
Fix: Update the agent, then select Retry.
Verify: The build creates a release.
Built but not deployed
the image was built and pushed, but no release was created, so nothing was deployed and the previous release keeps serving: <reason>
Cause: The row reads Built · not deployed because the release was refused. Reasons include an image that runs as root without Run as user, a cluster agent too old for file mounts or a release command, and a mounted file whose variable is not set. A temporary refusal, such as the project's deploy limit or a deploy freeze, is retried; after 5 attempts the reason ends NebulaCtrl tried 5 times and stopped, so start a new build once that is resolved.
Fix: Resolve the reason. See Deployments. Then start a new build.
Verify: The new build creates a release and the row reads Built.
Queued, superseded and cancelled builds
Superseded by build #<n>
Cause: The row reads Superseded. A newer build of the same service and environment ended the queued and running builds. This is not a failure.
Fix: None. Follow the newer build.
Verify: The newer build reads Building or Built.
tag <tag> did not appear within 15m0s
Cause: A service with a push trigger and an image source waits for the rendered tag in its registry, checking every 20 seconds, and the tag never appeared.
Fix: Push the image with the tag that Tag template renders, then select Retry.
Verify: The build succeeds and creates a release.
service <id> has no git source to build
Cause: The API answers 422 when you request a manual build for a service whose source is an image, or a Git source with no connection.
Fix: Set a Git repository under Source, or deploy the image instead. See Deploy from Git.
Verify: The build is Queued.
build <id> is <status>, not failed or cancelled
Cause: The API answers 409 when you retry a build that is queued, running or succeeded. Only failed or cancelled builds retry.
Fix: Wait for the build to end or select Cancel on it first.
Verify: Retry queues a new build from the same commit.
build <id> has already finished
Cause: The API answers 409 when you cancel a build that ended. Cancel build stops a queued or running build, which then reads Cancelled.
Fix: None. Select Retry to build the commit again.
Verify: The row shows its final status.
Deployments
Find the message a refused, waiting, failed or stalled deployment shows, and fix its cause: approvals, deploy order, freezes, capacity, image pulls, startup and readiness.
Clusters and agents
Find the message from a failed cluster install, a disconnected or degraded cluster, or a rolled-back agent update, and fix its cause.