Troubleshooting builds
Start on the deployment's page. Why the build failed sits under the header, in red:
Build failed. web: npm run build: process "npm run build" did not complete successfully: exit code: 1
It names the step that failed and its exit code. The step's output is in the
build log: click the service's build card on the
deployment's page, and read the lines above the one that starts with ERROR. A build on GitHub Actions
fails with Build failed. web: a build step failed; the run on GitHub, linked at the top of
the log, has the full output. From the CLI, ployz logs --deployment N --build web prints
the same log. Your current version keeps running.
Fix the cause and deploy again. Redeploy uses the same commit and settings, so it only helps when the fix was on a server.
Railpack can't tell how to build my app
Section titled “Railpack can't tell how to build my app”You'll see Railpack preparation failed: exited with exit status: 1. The lines above it say
why.
- In a monorepo, set the app's folder, like
/apps/web, as its root directory. - Commit the files Railpack looks for, like
package.jsonand its lockfile. See Railpack's docs. - If your app needs something Railpack can't guess, add a
railpack.json, or build with a Dockerfile.
The build passes, but my app never starts
Section titled “The build passes, but my app never starts”The image starts the wrong command, or none, and the service's card on the deployment's page
shows the failure. Set
Start command under Settings → Deploy, like node server.js, and deploy. See
Troubleshooting deployments for other reasons.
Ployz can't find my root directory or Dockerfile
Section titled “Ployz can't find my root directory or Dockerfile”You'll see Could not acquire the pinned repository source.,
Dockerfile must be a file inside the repository. or
Build root must be a directory inside the repository.
Check Root directory under Settings → Source and Dockerfile path under
Settings → Build against that commit. The Dockerfile path starts from the root directory:
with root /apps/web, a Dockerfile at apps/web/Dockerfile is just Dockerfile.
Installing a private package fails
Section titled “Installing a private package fails”You'll see 401 or 403 while the build installs a private package or Git repository.
Builds have no SSH keys or logins of their own: give the build a token through a secret
variable. See Install private packages.
A Dockerfile can't start FROM a private image either: use a public one.
A build step can't reach a server or service
Section titled “A build step can't reach a server or service”Build steps reach the internet. They don't reach your servers' private network, your services on
it, or the build server's local network, like a cloud VPC or office LAN. That includes an HTTP
proxy or a cloud endpoint at a private address, and a port published only on a private address.
Only port 53 stays open, so DNS keeps working. Move that call out of the build and into the service's start, or fetch the data from the internet.
The same goes for a Dockerfile ADD of a URL and for FROM, which can fail with i/o timeout:
a base image on a LAN registry or mirror won't pull, nor will one from a registry whose name
your network resolves to a private address, like a cloud endpoint with private DNS. Pull from an
address that resolves publicly instead.
See
What a build can reach.
A build step fails with exit code 137
Section titled “A build step fails with exit code 137”The build ran out of memory.
- Build on a bigger server, set as the service's Preferred Builder, or on GitHub Actions.
- Lower the server's Builds at once, so fewer builds share its memory.
- If the server caps build memory, raise
memory_bytes. See Build resources and cache. - For Node, add a variable like
NODE_OPTIONS=--max-old-space-size=2048.
My build is waiting its turn
Section titled “My build is waiting its turn”The build waits until a builder can take it.
- If the log shows
Waiting for a build slot, the server named above it is already running as many builds as it allows, maybe for another project. Raise its Builds at once on the server's page, or let more servers run builds. - If the log shows
Building on GitHub Actions:, follow its link: the run is waiting for a runner. - Another deployment in the environment may still be rolling out.
To stop waiting, click Cancel on the deployment's page.
No server can take my build
Section titled “No server can take my build”You'll see No eligible Build Machine was selected; no build was started., followed by why each
server was turned down, such as Server m1 (…): builds are turned off.
- On Servers, check your servers are online.
- Turn on Run builds here on at least one server.
- If your servers mix x86 and ARM, see When your servers mix x86 and ARM.
- Or pick a build order that ends with GitHub.
The build log says "GitHub skipped"
Section titled “The build log says "GitHub skipped"”You'll see GitHub skipped: …, and the next builder in your build order takes the build. If
GitHub was last, the deployment fails with …No other Builder in your Build Order can take it.
Pick a build order that includes your
servers, or fix the reason after the colon:
GitHub builds need the Ployz GitHub App on acme/web: connect GitHub and give the app the repository.acme/web has no .github/workflows/ployz-build.yml on its default branch: add it from Organization → Builds, and check it's enabled in the repository's Actions tab.the Ployz GitHub App can't run Actions in acme/web: approve Actions: Read and write for the Ployz GitHub App in GitHub.GitHub builds one platform, and this Service runs on linux/amd64 and linux/arm64: a service on both x86 and ARM servers builds on your servers.GitHub builds need a newer Ployz on web-1: upgrade Ployz on that server.no runner started the build in time,the run ended before it started the build,the run ran out of timeorthe run ended without pushing an image: check the run on GitHub. If it's still queued, your GitHub account may be out of Actions minutes or at its limit of jobs.
My build stops after 30 minutes
Section titled “My build stops after 30 minutes”You'll see the build exceeded its 1800s execution timeout and was terminated. Make the build
faster, build on GitHub Actions, which
allows 2 hours, or give builds more time
on the server.
My deploy fails on an ARM or x86 server
Section titled “My deploy fails on an ARM or x86 server”You'll see Build for Service web contains linux/amd64; destination Machine … reports architecture aarch64.
A Dockerfile image only runs on the kind of CPU it was built on, and nothing changed on your
servers. Switch the service to Railpack, or see
When your servers mix x86 and ARM.
Railpack builds only linux/amd64 and linux/arm64 means a server has another kind of CPU,
like 32-bit ARM. Ployz can't build for it.
The build server runs out of disk
Section titled “The build server runs out of disk”You'll see no space left on device.
By default, build servers free cache to keep a fifth of their Docker disk free. These steps help when that isn't enough:
- Clear the build cache, CLI-only for now: run
ployz server build-cache-clearon the server as root. - Remove images you don't use with
docker image prune. - Cap the build cache, or build on a server with more disk, or on GitHub Actions.
A build says its builder stays quarantined
Section titled “A build says its builder stays quarantined”You'll see builder ployz-1000 stays quarantined: the Build that last used it never confirmed its end, and still running: …. A build stopped without confirming that its work ended, often
because a cancelled GitHub Actions job was killed mid-build. Ployz won't reuse the builder
while that build might still be writing to it.
The message names each process that is still running. Once they have all stopped, the next
build on that server takes the builder back without any action from you. The same check runs
when the Ployz daemon starts and when you run ployz server build-cache-clear. If a named process hangs, stop it by
its PID. If the message says removing the builder failed, check that Docker is running on
the server.
My repository is too big or uses submodules
Section titled “My repository is too big or uses submodules”You'll see one of these:
Source archive exceeds the source size limit.: the commit is over 256 MB compressed or 2 GB unpacked.Source archive has too many or duplicate entries.: it has more than 100,000 files and folders.Git submodules are not supported for Cloud builds.orGit LFS content is not supported for Cloud builds.
Move large files, like datasets and media, out of the repository and fetch them during the build or when the app starts. Copy a submodule's code into the repository, or install it as a private package.
My Git branch is gone
Section titled “My Git branch is gone”You'll see The source branch no longer exists. or Reconnect web's branch before deploying.
Pick a Git branch under Settings → Source → Branch and deploy.
GitHub didn't answer
Section titled “GitHub didn't answer”You'll see GitHub didn't answer while reading the source. Deploy again. or
Repository is not connected to this Organization. Deploy again. If it keeps failing, check
the Ployz GitHub App can still see the repository: Create → GitHub repository → Add from
GitHub.
A GitHub build says a server belongs to another cluster
Section titled “A GitHub build says a server belongs to another cluster”You'll see Machine … belongs to another Cluster when a build on GitHub Actions finishes. The server
the build pushed its image to now belongs to another cluster, so Ployz Cloud can't confirm the build and
fails it. Deploy again: the new build uses one of this cluster's servers. If that server moved by
mistake, remove it from the other cluster and add it back.
The build queue is full
Section titled “The build queue is full”You'll see Build queue is full; execution was not attempted. Deploy again once the server has
caught up, or let more servers run builds.
Related
Section titled “Related”- How builds work
- Troubleshooting deployments: failed health checks and crashing services