CupaDev
Get Started
← Back to Documentation

Error Codes & Troubleshooting

A complete reference of errors you may encounter on CupaDev — build errors, runtime crashes, and configuration issues — with step-by-step fixes.

Where to find errors

Go to your project dashboard → Logs tab → Pod Logs to see your container's stdout/stderr in real time. Build errors are in the Build Logs tab.

Build Errors

EXIT 137

Build killed — out of memory (OOM)

The build process was killed by the OS because it consumed too much RAM. This typically happens during npm install or large TypeScript compilations.

Common causes

  • •A very large node_modules (e.g. Prisma + many dependencies)
  • •Running prisma generate via npx which downloads the full Prisma package
  • •Build command compiles a very large TypeScript project

How to fix

  1. Make sure you are NOT running npx prisma generate in a Dockerfile — CupaDev handles this automatically.
  2. Split very large monorepos into smaller services.
  3. If the error persists, contact support — we can increase your build pod memory limit.
EXIT 1 — BUILDKIT

BuildKit component missing

Docker tried to use BuildKit but the buildx plugin is not installed on the build host.

Common causes

  • •DOCKER_BUILDKIT=1 set in a custom Dockerfile or environment
  • •Using docker buildx commands in a build script

How to fix

Remove any DOCKER_BUILDKIT=1 environment variable from your project settings or Dockerfile. CupaDev uses the standard Docker builder.

MODULE NOT FOUND

Cannot find module 'X'

A required npm package is missing at runtime. The app starts but immediately crashes because a module cannot be resolved.

Common causes

  • •Package is in devDependencies but needed at runtime
  • •Monorepo: package installed in a subdirectory (backend/) not reachable from root
  • •Package name is misspelled in the import statement

How to fix

  1. Move the package from devDependencies to dependencies in package.json.
  2. For monorepos: CupaDev automatically merges subdirectory dependencies into root. Make sure your backend package.json lists all required packages.
  3. Redeploy after fixing.
PRISMA — BINARY TARGET

PrismaClientInitializationError: wrong binary target

Prisma was generated for a different OS/architecture than the deployment container.

Common causes

  • •Prisma client generated on macOS (darwin) then deployed to Alpine Linux
  • •schema.prisma missing linux-musl-openssl-3.0.x in binaryTargets

How to fix

CupaDev automatically patches your schema.prisma to add the correct target. If you see this error:

  1. Make sure your schema.prisma is committed to your repository (not in .gitignore).
  2. Add the target manually as a safety net:
generator client {
  provider      = "prisma-client-js"
  binaryTargets = ["native", "linux-musl-openssl-3.0.x"]
}
  • Trigger a new deployment.
    • TYPESCRIPT BUILD FAILED

    TypeScript compilation errors

    tsc reports type errors and the build fails before producing output.

    Common causes

    • •Type errors in source code that were previously ignored locally
    • •Strict mode differences between local tsconfig and production
    • •Missing @types/* packages

    How to fix

    1. Run tsc --noEmit locally to see all errors before pushing.
    2. Add "skipLibCheck": true to your tsconfig.json to ignore type errors in node_modules.
    3. If you want to deploy despite TS errors, use a build script that ignores them: "build": "tsc --skipLibCheck --noEmitOnError false".

    Runtime Errors

    CRASHLOOPBACKOFF

    Pod is in CrashLoopBackOff

    The container starts, crashes immediately, and Kubernetes keeps restarting it in an exponential backoff loop.

    Common causes

    • •Missing required environment variable (DATABASE_URL, SECRET_KEY, etc.)
    • •Application throws an uncaught exception at startup
    • •Wrong start command (app tries to run a file that doesn't exist)
    • •Port mismatch (app listens on 8080 but container expects 3000)

    How to fix

    1. Open Project → Logs → Pod Logs — the crash reason is always visible there.
    2. Check that all required env vars are set in Project → Environment Variables.
    3. Make sure your app listens on PORT (injected automatically): const port = process.env.PORT || 3000.
    4. After fixing env vars, click Redeploy.
    UNTRUSTED HOST

    Auth.js / NextAuth: UntrustedHost error

    NextAuth v5 (Auth.js) rejects requests because the host is not in its trusted list. This blocks readiness probes and all auth flows.

    Common causes

    • •AUTH_TRUST_HOST env var not set
    • •NEXTAUTH_URL not set or pointing to wrong domain
    • •App deployed behind a reverse proxy (Traefik, Nginx) without forwarding X-Forwarded-Host

    How to fix

    Add these environment variables in Project → Environment Variables:

    AUTH_TRUST_HOST=true
NEXTAUTH_URL=https://your-project.cupadev.com

    Then click Redeploy.

    ECONNREFUSED / DB CONNECT

    Database connection refused

    The app cannot connect to the database at startup.

    Common causes

    • •DATABASE_URL not set or incorrect
    • •Database host not accessible from CupaDev network
    • •Wrong port in connection string
    • •SSL required but not configured

    How to fix

    1. Verify DATABASE_URL is set in Project → Environment Variables.
    2. Use the full connection string including credentials and port: postgresql://user:pass@host:5432/db.
    3. If using Supabase/Neon/Railway, append ?sslmode=require to the URL.
    4. Make sure the database allows connections from external IPs (disable IP allowlist or whitelist 0.0.0.0/0).
    PORT NOT LISTENING

    Service unavailable / No available server

    The deployment is live but requests return 502 or 'No available server'. The container is running but not accepting connections.

    Common causes

    • •App listening on 127.0.0.1 instead of 0.0.0.0
    • •App hardcoded to a port different from PORT env var
    • •App crashes after a few seconds (check Pod Logs)

    How to fix

    1. Bind to 0.0.0.0, not localhost: app.listen(port, '0.0.0.0').
    2. Always use the PORT environment variable: process.env.PORT || 3000.
    3. For Next.js, make sure HOSTNAME="0.0.0.0" is set (CupaDev sets this automatically).
    REDIS DISCONNECTED

    Redis connection error

    The app reports Redis as disconnected at startup.

    Common causes

    • •REDIS_URL not set
    • •Redis not provisioned for this project

    How to fix

    1. Set REDIS_URL in your environment variables.
    2. If Redis is optional in your app, make it fault-tolerant: catch connection errors and continue without Redis.

    Configuration Issues

    WRONG FRAMEWORK

    App detected as wrong framework

    CupaDev auto-detects your framework but may pick the wrong one (e.g. detects Node.js instead of Next.js).

    Common causes

    • •Both express and next.js in dependencies
    • •Missing next.config.js
    • •Custom monorepo structure

    How to fix

    1. In your project settings, manually set the framework override.
    2. Make sure next (or your framework) is in dependencies, not just devDependencies.
    BUILD COMMAND FAILS

    Custom build command not working

    Your overridden build command exits with a non-zero code.

    Common causes

    • •Command not available in the build container (e.g. make, cargo)
    • •Missing environment variable needed during build
    • •Incorrect working directory

    How to fix

    1. Use Node.js-compatible build commands. The builder container has Node 20, npm, and standard Unix tools.
    2. Build-time environment variables must be declared in Environment Variables — they are injected automatically.
    3. Test your build command locally first: npm run build.

    Required Environment Variables by Framework

    FrameworkRequired variablesNotes
    Next.js + Auth.jsAUTH_SECRET, AUTH_TRUST_HOST=true, NEXTAUTH_URLAUTH_SECRET must be at least 32 chars
    Next.js + PrismaDATABASE_URLschema.prisma must be committed
    Express / Node.jsPORT (auto-injected)Listen on 0.0.0.0, not localhost
    Any app with DBDATABASE_URLInclude SSL params if required
    Any app with RedisREDIS_URLFormat: redis://user:pass@host:6379
    Stripe integrationSTRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRETUse test keys for staging

    Still stuck?

    Check the Pod Logs tab in your project dashboard — the error message is always there. If you cannot resolve it, contact support with the full log output.

    Contact Support