Skip to content

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.

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.json and 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 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.

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.

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.

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.

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.

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 time or the 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.

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.

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.

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-clear on 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. or Git 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.

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.

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.

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.