Build & deploy failures

When a deploy fails, the answer is almost always in the live build logs — they stream in real time while the build runs, and the failing command’s output is printed exactly as it happened. Open the failed deployment, read the last lines of the log, then find the matching symptom below. See Build & buildpacks for how the build pipeline works end to end.

”npm run build” (or next build / tsc / vite / go build) exited with a non-zero code

Your build failed inside your own build command — the compiler or bundler rejected your code.

Why this happens. PandaStack runs your project’s build command (npm run build, next build, tsc, vite build, go build, and so on). If that command exits non-zero — a type error, a missing import, a syntax error — the build fails. This is not a platform error: the exact compiler or bundler error is printed in the live build logs.

Fix

1. Read the build logs and find the underlying compiler/bundler error (it is usually a few lines above the final “exited with code 1”).
2. Reproduce it locally by running the same build command on your machine.
3. Fix the error and push. A new deploy starts automatically when auto-deploy is on — or click Deploy to trigger one manually.

Dependency install fails (npm ci / EUSAGE lockfile error, pip or go module resolution errors)

The build dies before your code even compiles — during npm ci, pip install, or Go module download.

Why this happens. The most common cause on Node projects is a package-lock.json that is out of sync with package.json: npm ci refuses to run and reports an EUSAGE lockfile error. Missing or conflicting peer dependencies fail the same step. Python and Go projects fail here on unresolvable package or module versions. A second cause: your project depends on a private npm registry — builds have no access to private registries unless you provide credentials via environment variables.

Fix

1. Run npm install locally and commit the updated package-lock.json, so the lockfile matches package.json again.
2. Resolve peer-dependency conflicts locally until a clean install works, then commit.
3. If you need a private registry, supply its credentials as environment variables so the install step can authenticate.

Build fails or misbehaves because of the Node version

The build runs with a different Node version than you expected, or a framework refuses to build on the selected version.

Why this happens. PandaStack auto-selects a suitable Node version rather than blindly trusting your package.json:

• Framework minimums are enforced automatically. For example, Next.js requires Node >= 18.17 — your build gets a version that satisfies it even if your package.json declares an older range.
• Open-ended ranges resolve high. A range like ">=14" resolves to Node 22.

Fix

Pin an exact version and the buildpack respects it:

• Set "engines": { "node": "20.x" } in package.json, or
• Add a .nvmrc or .node-version file to the repo root.

See Build & buildpacks for the full version-selection policy.

The image built successfully, but nothing starts

The build log shows a successful image build, then the deploy fails because there is no process to run.

Why this happens. The container has no start command. With the auto language, Railpack detects your start script (for example, the "start" script in package.json) — but the nodejs language requires an explicit start command; without one, there is nothing to launch.

Fix

• Add a "start" script to your package.json, or
• Set the Start Command under the project’s Advanced settings.

Build succeeded, but the deploy fails — the app never becomes healthy

The build passes, the app appears to start, and then the deploy is marked failed anyway.

Why this happens. The health check can’t reach your server. Your server must listen on host 0.0.0.0 and on the port PandaStack provides in the PORT environment variable. Binding to 127.0.0.1 or localhost means the health check cannot connect, so the deploy fails after a successful build. Common dev servers (vite preview, next start, and similar) are automatically passed --host 0.0.0.0 by the platform — but a custom server must do this itself.

Fix

In a custom server, read the port from the environment and bind all interfaces:

const port = process.env.PORT;
app.listen(port, '0.0.0.0');

Then redeploy.

The build or the running app is killed (out of memory)

The log ends abruptly with the process being killed, or the running app restarts under memory pressure.

Why this happens. The build or the application exceeded its memory limit and was OOM-killed.

Fix

• Choose a larger instance tier under the project’s Resources — paid tiers have more memory; see Instance tiers.
• Or reduce memory usage — for example, disable source maps in the production build.

PandaStack can’t fetch your repository

The deploy fails before any build output — the platform could not get your code.

Why this happens. Either the branch you configured doesn’t exist, or the repository is private and the PandaStack GitHub App isn’t installed (or wasn’t granted access to that specific repo).

Fix

1. Check the branch name on the project matches a branch that actually exists in the repo.
2. For private repos, connect GitHub on the create-project page and grant the App access to the repository.
3. If you’re deploying a specific commit, use the full commit SHA — deploying a specific commit is supported.

Static upload rejected: “No index.html at the root”

You uploaded a zip of your built site and the deploy was rejected.

Why this happens. A servable static site needs index.html at the top level of what you upload. The usual mistake is zipping the dist/ or build/ folder instead of its contents, which buries index.html one directory down.

Fix

• Zip the contents of your dist/ or build/ folder, not the folder itself.
• Note that the dashboard uploader auto-fixes a single wrapping folder, and the drag-a-folder flow zips correctly for you — so uploading through the dashboard usually avoids this entirely.

See Static sites for the upload flow.

Static upload rejected: file too large

The upload is refused because the archive exceeds the size cap.

Why this happens. Static uploads are capped at 30 MB (compressed) on the Free plan and 100 MB on paid plans.

Fix

• Compress images and drop source maps from the production build to shrink the archive, or
• Upgrade to a paid plan for the 100 MB cap — see Plans.

Deploy blocked by the Acceptable Use Policy

The deploy is rejected with an abuse-policy message rather than a build error.

Why this happens. An automated content scan blocks deployments that match abuse patterns — gambling/betting, adult content, proxy/VPN tooling, and malware-style obfuscation.

Fix

If your legitimate project was blocked in error, contact support@pandastack.io and the team will review it.

Builds feel slow

Every build seems to take a long time, or a redeploy takes as long as the first build.

Why this happens. The first build of a project is a cold build — nothing is cached yet. Redeploys reuse the build cache: unchanged dependency layers (for example, npm ci with an unchanged lockfile) are skipped entirely, so subsequent builds are much faster. Also note that build minutes are metered per plan — 300/month on Free, 1,000 on Pro, 2,500 on Premium — see Usage & metering.

Fix

• Expect the first build to be slow; check whether redeploys are fast — that’s the cache working.
• Keep your lockfile stable between deploys so the dependency layer stays cached.

Deployed fine, but the first request is slow or times out

The app is live, but the first hit after a quiet period hangs for several seconds or times out.

Why this happens. Free-tier container apps scale to zero when idle. The first request wakes the app — a cold start of a few seconds. Paid tiers with autoscaling stay always-warm.

Fix

• If cold starts are acceptable, retry the first request — subsequent requests are fast while the app is warm.
• If not, move to a paid tier with autoscaling so the app stays always-warm — see Scaling.

Environment variable changes don’t apply

You edited an env var or secret, but the running app still sees the old value.

Why this happens. Environment variables and secrets are applied at deploy time. Editing them does not change a running deployment.

Fix

After editing env vars or secrets, trigger a redeploy so the new values are baked into the deployment. See Environment variables & secrets.

Still stuck?

Grab the last lines of the live build logs from the failed deployment (they contain the exact failing command and its output) and email support@pandastack.io — including the log excerpt and the project name gets you a much faster answer.