Docs menu
Troubleshooting Node.js
Common build and runtime errors for Node.js apps on Primcloud, with the fix for each.
On this page
Build failures show in the deployment's build log, from installing Node.js through your build scripts. Runtime problems, like startup crashes, unhandled promise rejections, and native modules that won't load, show in the Logs tab.
Common build errors#
No Node.js application found#
The build looked for a package.json at the repo root and didn't find one.
Fix. Move the package.json to the repo root. Primcloud builds from the root of your repo.
Unknown Node.js version#
The engines.node range in package.json doesn't match any Node.js release in the Primcloud Runtime, either because it isn't a real release or because it pins one that isn't available yet.
Fix. Use a version from Runtime versions, or loosen an exact version to a range like "24.x".
Node.js version is End-of-Life#
The build log warns Node.js <version> is now End-of-Life (EOL). The build succeeds, but a later update will make this a build error.
Fix. Move engines.node to a supported version. See End-of-life versions.
Missing lockfile / dependencies not installed#
The build log shows Node.js installing but no dependencies, because the repo has none of package-lock.json, pnpm-lock.yaml, or yarn.lock.
Fix. Run npm install, pnpm install, or yarn install locally, commit the generated lockfile, and redeploy. See Package managers → Lockfiles.
Wrong lockfile / package manager mismatch#
package.json names pnpm (in packageManager or engines.pnpm) but the repo has a package-lock.json, so the install fails without a pnpm-lock.yaml.
Fix. Commit the lockfile for the package manager you use, and delete the others.
npm ci / pnpm install / yarn install fails#
Usually the lockfile disagrees with package.json, after an edit or a merge that didn't regenerate it, or a dependency points at a git or file URL the build can't reach.
Fix. Reproduce locally with the same command the build runs:
npm ci
pnpm install --frozen-lockfile
yarn install --immutable # Yarn 2+
yarn install --frozen-lockfile # Yarn 1
If it fails locally too, regenerate the lockfile, fix the version conflict, or make the URL reachable. If it passes locally, check the lockfile is committed.
Build script failed: heroku-prebuild / heroku-build / build / heroku-postbuild#
One of your build scripts exited non-zero. Its output is in the build log just above the error.
Fix. Read the script's stderr and address it. Reproduce locally with the same command:
npm run build
Common causes are TypeScript errors, an environment variable the build needs that isn't set as a secret, and running out of memory during bundling (see Out of memory).
Native module fails to compile: node-gyp errors#
A package with native code (sharp, bcrypt, sqlite3, canvas) failed to build. The node-gyp output above the error usually names the missing header or library.
Fix. Two paths:
- If the package publishes prebuilt binaries (most modern ones do) and the build is trying to compile from source anyway, check the package's install docs. You may need a secret like
SHARP_IGNORE_GLOBAL_LIBVIPS=1to use the prebuilt binary. - If the package needs a system library (
libvips,libpq, ImageMagick), add it toproject.toml; see Debian packages.
Cannot find module '...'#
A require() or import resolves to nothing.
Fix. Common causes:
- It's a
devDependency, which can be pruned after the build. Move it intodependencies. - It's generated code that isn't committed, and nothing in the build generates it. Add the generator to
buildorheroku-postbuild. - A relative import has the wrong case. macOS and Windows ignore case in file names; Linux doesn't, so
import Foo from './foo'can work locally and fail on Primcloud.
Common runtime errors#
App doesn't bind to $PORT#
The deployment fails while waiting for your web process to accept connections.
Fix. Listen on process.env.PORT. No other port receives traffic.
const port = process.env.PORT || 3000;
app.listen(port, () => console.log(`listening on ${port}`));
Listen on 0.0.0.0 or leave the host out. A server listening only on 127.0.0.1 gets no traffic.
App exits immediately on start#
Your logs show the process starting and exiting, or an uncaught exception at startup. Common causes:
- A missing environment variable. Add it as a secret.
- The wrong entry point. Check your
startscript points at your actual entry file.
Out of memory on start or during build#
The build log or your logs show FATAL ERROR: Reached heap limit Allocation failed.
Fix.
- During the build, usually while bundling: set a
NODE_OPTIONS=--max-old-space-size=2048secret. - At runtime: move to a larger compute size, or raise the heap limit with a
NODE_OPTIONS=--max-old-space-size=<mb>secret.
Native addon fails to load at runtime#
Error: Cannot find module '.../node_modules/sharp/build/Release/sharp.node'
or
Error: /lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_...' not found
A native module built but can't load, often because a system library it needs isn't installed.
Fix. Add the library to project.toml; see Debian packages.
Debugging tips#
- Run the build's commands locally.
npm ci(or the pnpm or Yarn equivalent) andnpm run buildreproduce most build failures. If they pass locally, the difference is usually an environment variable your build reads. - Check the Node.js version. The build log shows the version it installed. If it isn't what you expected, tighten your
engines.noderange. - Turn on debug output. A
DEBUG=*secret, or a narrower one likeDEBUG=express:*, makes modules that usedebugprint their traces. Remove it when you're done.