Deploy failed: how to read build errors

A failed build usually dumps a wall of text: warnings, stack traces, deprecation notices and a final line that says the command exited with an error. Most of it is noise. One line, often far above the end, names the real problem.

Finding that line is a short routine, and the errors it uncovers in Node.js and Python builds repeat a lot. Each one has a known fix. If "build" and "deploy" are still blurry terms, start with what a deployment is.

Which line of a build log matters?#

Read the log from the top, not the bottom. Build tools stop at the first failure, but they keep printing: the package manager reports that a script failed, then that the install failed, then the exit code. Those last lines describe the consequence, not the cause.

Use this routine:

1. Search the log for error, ERR!, ERROR: or FATAL.
2. Take the first hit that is not a warning.
3. Read the 5 to 10 lines around it. Package managers print the conflicting names and versions right there.
4. Copy the exact message into your search. The literal text finds answers faster than a paraphrase.

Warnings (npm warn deprecated ...) rarely break a build. Treat them as noise until you've found a real error.

Why does npm print ERESOLVE?#

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: my-app@1.0.0
npm error Found: react@19.0.0
npm error node_modules/react
npm error   react@"19.0.0" from the root project
npm error
npm error Could not resolve dependency:
npm error peer react@"^18.0.0" from some-library@2.1.0

A package declares a peer dependency, meaning "my host project must provide this package in this version range". Your project provides a different version, so npm can't build a consistent tree. By default npm resolves some conflicts with the nearest non-peer dependency and prints a warning. With strict-peer-deps on, or when the conflict cannot be resolved, it becomes a failure.

Fixes, from best to worst:

• Upgrade some-library to a release that supports your version.
• Downgrade or pin the package you control, if you can't upgrade the library.
• Pass --legacy-peer-deps. npm documents it as ignoring peerDependencies completely, as npm 3 to 6 did. The build passes, but the incompatibility is still there.

Avoid --force as a fix. According to the npm docs, it removes protections against unfortunate side effects, and npm strongly recommends against it if you don't have a clear idea of what you want to do.

If you create the lockfile with --legacy-peer-deps, pass the same flag to npm ci, or the install is likely to fail.

Why does npm ci fail when npm install works?#

npm error code EUSAGE
npm error
npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
npm error
npm error Missing: express@5.1.0 from lock file

npm ci is the install command for automated builds. It needs an existing package-lock.json, and if the lockfile and package.json disagree, it exits with an error instead of updating the lockfile. That's deliberate: every build installs the exact versions you tested.

The fix is local. Run npm install, commit the changed package-lock.json, and deploy again.

What does "Cannot find module" mean, and why does it fail only on the server?#

Two different tools print similar text.

Error: Cannot find module 'express'

This is Node.js loading a CommonJS module. With ES modules (import), the same problem reads Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'express' imported from .... Either way, the package is not installed, or it is listed in devDependencies while the build runs a production-only install. Check package.json first, then check that the import path matches the file name exactly, including capital letters. A file called Utils.js imported as ./utils works on Windows and macOS but fails on Linux.

src/index.ts(3,20): error TS2307: Cannot find module './utils' or its corresponding type declarations.

This is the TypeScript compiler. Either the file does not exist at that path, or TypeScript cannot find types for a package. Install the matching @types/... package or check moduleResolution: the TypeScript docs say it should match the resolver of your runtime or bundler. Remember that paths aliases affect type checking but not emitted code, so code can compile and still fail when it runs.

Why do versions differ between your laptop and the build?#

Version drift causes many of these failures, because your laptop and the build environment rarely run the same version. A syntax feature, a native module or a package release may exist in one and not the other.

Declare the version you tested. In Node.js, add an engines field to package.json:

{
  "engines": {
    "node": ">=22"
  }
}

By default npm treats engines as advisory and only warns, and only when your package is installed as a dependency. It doesn't stop your own build unless engine-strict is set. For Python, state the interpreter version in your project docs or tooling and pin packages in requirements.txt.

What do pip build errors mean?#

ERROR: Could not find a version that satisfies the requirement somepackage==9.9
ERROR: No matching distribution found for somepackage==9.9

The version does not exist, or no file of it fits your Python version and platform. Check the exact name and version on PyPI, and check that the package supports your Python version.

ERROR: Cannot install package_a==1.0 and package_b==2.0 because these package versions have conflicting dependencies.

The conflict is caused by:
    package_a 1.0 depends on package_c<3.0,>=2.4
    package_b 2.0 depends on package_c==2.3

This is pip's ResolutionImpossible. Read the "conflict is caused by" block: two packages need incompatible ranges of a third. Loosen your own pins, remove packages you don't need, or upgrade one of the two.

error: command 'gcc' failed: No such file or directory
ERROR: Failed building wheel for somepackage

Some packages ship no prebuilt wheel for your platform, so pip compiles them from source, which needs a compiler and system headers. Prefer a version that publishes a wheel. The --only-binary :all: option makes pip refuse source builds, so it fails fast if no wheel exists.

What if the build runs out of memory?#

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

The middle of the message varies with the situation (for example Ineffective mark-compacts near heap limit), but it ends with JavaScript heap out of memory.

Or the build simply stops with exit code 137, which by shell convention is 128 plus signal 9 (SIGKILL). Bundlers, TypeScript on a large project and image processing can use more memory than a small container allows. Node.js documents --max-old-space-size (in MiB) as the limit for V8's old memory section, and suggests about 1536 on a machine with 2 GiB to leave room for other uses:

NODE_OPTIONS=--max-old-space-size=1536 npm run build

Raising the limit only helps if the machine really has that memory. If it doesn't, the system kills the process, and that's the 137. You're then left with two options, more RAM for the build or less work per build: disable source maps, split the project, or build locally and upload the output.

How do you stop the same failure from coming back?#

• Build the way the server builds: delete node_modules and run npm ci, or create a clean virtual environment and run pip install -r requirements.txt.
• Commit lockfiles and pin runtime versions.
• Check configuration early. Missing environment variables fail late and confusingly, so read what environment variables are.
• Run the build in CI before deploying, as in automatic deploys with GitHub Actions.
• Know your memory budget. Sizing RAM and CPU explains how to estimate it.

How to do this on Square Cloud#

On Square Cloud the reading routine is the same, but the error shows up at a different moment, because there is no build step. On start, the platform installs dependencies (npm install when there is no node_modules, without devDependencies, or pip install -r requirements.txt for Python), and that install output shows up in the application logs. If your project needs compiling, run the build in an external CI such as GitHub Actions and send the result, or put the build in the start command.

You deploy by ZIP upload, the CLI, GitHub or the VS Code extension. Logs stream in real time in the dashboard, the CLI and VS Code, so you can read the first error line as soon as it appears.

Memory is yours to set. An application can use up to 32 GB from the plan's shared RAM pool, and you change the amount in the application settings or through the API, which helps if the application hits a heap error while it runs. Environment variables are set per application, and a change takes effect on the next restart without a rebuild. The Cubic agent in the dashboard can also read your logs to help diagnose failures, always at your request.

See what each runtime supports on the runtimes page.