Build Errors

Build errors occur during the Docker image build phase — before the container starts. If you see your deployment fail at the BUILDING stage, start here.

Node.js

npm ERR! Could not resolve dependency

Your package.json references a package version that conflicts with another dependency.

Fix: Run npm install locally to reproduce. Use npm install --legacy-peer-deps if peer dependency conflicts are the issue. Commit the updated package-lock.json.

Module not found: Can't resolve '...'

A JavaScript/TypeScript import references a module that is not installed.

Fix: Verify the import path. Check that the package is in dependencies (not just devDependencies) if it’s needed at runtime. If using path aliases, ensure they are configured in both tsconfig.json and your bundler config.

npm run build exits with error

The build script itself fails — often a TypeScript compilation error or a missing environment variable needed at build time.

Fix: Read the full build output in the deployment logs. The error message will point to the specific file and line. Run npm run build locally to reproduce.

ENOMEM or Killed during build

The build process ran out of memory on the server.

Fix: This is common for large Next.js or Webpack builds. Add a resource limit with more memory, or build the image locally and deploy it as a Docker image instead of a git deploy.

---

Python

ERROR: Could not find a version that satisfies the requirement

A package in requirements.txt doesn’t exist or the version constraint can’t be satisfied.

Fix: Check for typos in the package name. Verify the version exists on PyPI. If using private packages, ensure the package index is accessible during build.

ModuleNotFoundError: No module named '...'

An import in your code references a module that isn’t installed.

Fix: Add the missing package to requirements.txt or pyproject.toml. If it’s a local module, check your project structure — Clank’s auto-Dockerfile expects requirements.txt at the repo root.

SyntaxError in Python files

A syntax error in your code prevents the application from loading.

Fix: Run python -c "import py_compile; py_compile.compile('yourfile.py')" locally, or just run your app locally to surface the error.

---

Static sites

dist/ or build/ directory not found

The build command ran but the output directory doesn’t match what the Dockerfile expects.

Fix: Check your framework’s build output directory. React (build/), Vite (dist/), Next.js (.next/). If using a custom build directory, make sure the Dockerfile copies from the correct path.

---

General build issues

Custom Dockerfile fails

If you’ve added a Dockerfile to your repo, Clank uses it instead of auto-generating one. Errors in this Dockerfile are not Clank-specific.

Fix: Build the Dockerfile locally with docker build . to reproduce the error.

Auto-detected Dockerfile is wrong

Clank auto-detects your framework and generates a Dockerfile. Sometimes the detection is wrong — for example, detecting a Node.js SPA when you have a Node.js server.

Fix: Add your own Dockerfile to the repo root. Clank always prefers a user-provided Dockerfile over auto-detection. See Supported Languages for what Clank auto-detects.

Build works locally but fails on Clank

Common causes:

• Architecture mismatch: Your local machine is ARM (Apple Silicon) but the server is x86_64. Some packages have different behavior across architectures.
• Missing build-time env vars: Variables needed during npm run build or similar must be set in the service’s environment tab.
• Different Node/Python version: Clank’s auto-Dockerfile picks a default version that may differ from your local setup.

Next steps

• Deployment Failures — Covers post-build failures (health checks, crashes, resource issues).
• Auto-Dockerfile Detection — How Clank detects your framework.