Render Debug

Render Deployment Error Patterns

Comprehensive catalog of common deployment errors on Render, their causes, and fixes. Organized by frequency and category.

MCP Quick Detection

Use these MCP queries to quickly detect each error pattern:

Most Common Errors

1. MISSING_ENV_VAR (Most Common)

Description: Application crashes because required environment variable is not set.

MCP Detection:

list_logs(
  resource: ["<service-id>"],
  text: ["KeyError", "not defined", "undefined", "Missing required environment"],
  limit: 50
)

Patterns to Match:

• ReferenceError: DATABASE_URL is not defined

• TypeError: Cannot read property 'DATABASE_URL' of undefined

• KeyError: 'API_KEY'

• KeyError: 'JWT_SECRET'

• Environment variable not found: DATABASE_URL

• Missing required environment variable

• process.env.DATABASE_URL is undefined

• os.environ['DATABASE_URL'] KeyError

Common Variables:

• DATABASE_URL - PostgreSQL connection string

• REDIS_URL - Key Value connection string

• JWT_SECRET - Authentication secret

• API_KEY - Third-party API keys

• SECRET_KEY - Django secret key

• NEXTAUTH_SECRET - NextAuth.js secret

• SESSION_SECRET - Session encryption key

Root Causes:

1. Variable not declared in render.yaml

2. Variable marked with sync: false but user didn't fill in Dashboard

3. Typo in variable name (case-sensitive!)

4. Variable added to code but not to render.yaml

Fix Strategy:

1. Read environment-variables.md and determine whether the service is managed through a Blueprint, Dashboard configuration, or an API/MCP operation.

2. Inspect existing keys without exposing values, then add only the missing configuration through the intended source of truth.

3. Use current Blueprint resource references rather than copied connection strings, and use an appropriate secret mechanism for sensitive values.

4. Apply the applicable deploy and verify successful startup in logs.

Prevention:

• Keep the chosen configuration source authoritative

• Never commit or print secret values

• Double-check variable names (case-sensitive)

• Keep local secret-bearing .env files out of version control

2. PORT_BINDING_ERROR (Second Most Common)

MCP Detection:

list_logs(
  resource: ["<service-id>"],
  text: ["EADDRINUSE", "address already in use", "cannot assign requested address"],
  limit: 20
)

Description: Application not binding to correct port or host.

Patterns to Match:

• EADDRINUSE: address already in use

• Error: listen EADDRINUSE: address already in use 0.0.0.0:3000

• Address already in use (os error 48)

• Failed to bind to 0.0.0.0:3000

• Health check timeout (often caused by wrong port)

• cannot assign requested address

Root Causes:

1. App hardcodes port instead of using $PORT environment variable

2. App binds to localhost or 127.0.0.1 instead of 0.0.0.0

3. Multiple services trying to use same port

4. App doesn't read PORT environment variable

Fix Strategy:

Node.js / Express:

// Before (WRONG)
app.listen(3000);
app.listen(3000, 'localhost');

// After (CORRECT)
const PORT = process.env.PORT || 3000;
app.listen(PORT, '0.0.0.0', () => {
  console.log(`Server running on port ${PORT}`);
});

Python / Flask:

# Before (WRONG)
app.run(port=5000)
app.run(host='localhost', port=5000)

# After (CORRECT)
import os
port = int(os.environ.get('PORT', 5000))
app.run(host='0.0.0.0', port=port)

Python / Django (gunicorn):

# In render.yaml startCommand
startCommand: gunicorn config.wsgi:application --bind 0.0.0.0:$PORT

Go:

// Before (WRONG)
http.ListenAndServe(":3000", handler)

// After (CORRECT)
port := os.Getenv("PORT")
if port == "" {
    port = "3000"
}
http.ListenAndServe(":"+port, handler)

Prevention:

• Always use process.env.PORT (or equivalent)

• Always bind to 0.0.0.0

• Test with PORT=10000 locally

3. MISSING_DEPENDENCY

MCP Detection:

list_logs(
  resource: ["<service-id>"],
  text: ["Cannot find module", "ModuleNotFoundError", "ImportError", "package not found"],
  limit: 50
)

Description: Required package or module not installed.

Patterns to Match:

• Cannot find module 'express'

• Error: Cannot find module './config'

• ModuleNotFoundError: No module named 'django'

• ImportError: No module named flask

• package not found: github.com/gin-gonic/gin

• error: could not find tokio in the list of imported crates

Root Causes:

1. Dependency not in package.json/requirements.txt/go.mod

2. Wrong build command

3. Build cache issues

4. Dependency only in devDependencies

Fix Strategy:

Node.js:

// Add to package.json
{
  "dependencies": {
    "express": "^4.18.0",
    "pg": "^8.11.0"
  }
}

Python:

# Add to requirements.txt
django==4.2.0
psycopg2-binary==2.9.5

Go:

# Update go.mod
go get github.com/gin-gonic/gin

Prevention:

• Keep dependencies in sync with code

• Use lock files (package-lock.json, Pipfile.lock)

• Test build locally first

Configuration Errors

4. DATABASE_CONNECTION_FAILED

MCP Detection:

list_logs(
  resource: ["<service-id>"],
  text: ["ECONNREFUSED", "could not connect to server", "connection refused", "ETIMEDOUT"],
  limit: 50
)

MCP Investigation:

# Check database status
list_postgres_instances()

# Check connection metrics
get_metrics(
  resourceId: "<postgres-id>",
  metricTypes: ["active_connections"]
)

# Query database directly
query_render_postgres(
  postgresId: "<postgres-id>",
  sql: "SELECT count(*) FROM pg_stat_activity"
)

Description: Cannot connect to database.

Patterns to Match:

• ECONNREFUSED 127.0.0.1:5432

• could not connect to server: Connection refused

• FATAL: password authentication failed

• connect ETIMEDOUT

• Redis connection to 127.0.0.1:6379 failed

• SSL SYSCALL error: EOF detected

Root Causes:

1. DATABASE_URL not set

2. Wrong connection string format

3. Database not provisioned

4. SSL settings incorrect

5. Connection timeout too short

Fix Strategy:

Step 1: Verify DATABASE_URL is set in render.yaml

envVars:
  - key: DATABASE_URL
    fromDatabase:
      name: postgres
      property: connectionString

Step 2: Enable SSL if needed (Node.js example)

const { Pool } = require('pg');
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: process.env.NODE_ENV === 'production' ? {
    rejectUnauthorized: false
  } : false
});

Step 3: Check database provisioned

render services -o json
# Verify database exists and is active

5. INVALID_BUILD_COMMAND

Description: Build command fails.

Patterns to Match:

• npm ERR! missing script: build

• sh: line 1: webpack: command not found

• error: failed to compile

• SyntaxError: Unexpected token

• Error: Command failed with exit code 1

Root Causes:

1. Wrong build script name

2. Build tools not installed

3. Syntax errors in code

4. Build script doesn't exist

Fix Strategy:

Node.js - Check package.json:

{
  "scripts": {
    "build": "tsc",  // or webpack, vite, etc.
    "start": "node dist/index.js"
  }
}

Render.yaml:

buildCommand: npm ci && npm run build

Python - No build step needed:

buildCommand: pip install -r requirements.txt

Runtime Errors

6. HEALTH_CHECK_TIMEOUT

Read deployments.md for current health-check behavior, timing, and service-type support before interpreting this failure.

MCP Detection:

list_logs(
  resource: ["<service-id>"],
  text: ["Health check", "failed to become healthy", "timeout"],
  limit: 30
)

MCP Investigation:

# Check if service is binding correctly
list_logs(
  resource: ["<service-id>"],
  text: ["listening", "started", "running on port"],
  limit: 20
)

# Check CPU/Memory during startup
get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["cpu_usage", "memory_usage"]
)

Description: Service doesn't respond to health checks within timeout period.

Patterns to Match:

• Health check timeout

• failed to become healthy

• Service did not pass health check

• GET / returned status 404

Root Causes:

1. Configured health check endpoint is missing or incorrect

2. App not binding to correct port

3. Slow application startup

4. Health check path incorrect

5. Application crashes during startup

Fix Strategy:

Step 1: Add health check endpoint

Node.js:

app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok', timestamp: Date.now() });
});

Python / Flask:

@app.route('/health')
def health():
    return {'status': 'ok'}, 200

Step 2: Configure in render.yaml

healthCheckPath: /health

Step 3: Ensure fast startup

• Move slow initialization to after server start

• Use lazy loading for heavy operations

7. OUT_OF_MEMORY (OOM)

MCP Detection:

list_logs(
  resource: ["<service-id>"],
  text: ["heap out of memory", "Killed", "OOMKilled", "exit code 137", "cannot allocate memory"],
  limit: 30
)

MCP Investigation:

# Check memory usage trend
get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["memory_usage", "memory_limit"]
)

# Check if memory usage spiked
get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["memory_usage"],
  startTime: "<before-crash-time>"
)

Description: Application exceeds available memory.

Patterns to Match:

• JavaScript heap out of memory

• FATAL ERROR: Reached heap limit Allocation failed

• Killed (exit code 137)

• OOMKilled

• cannot allocate memory

Root Causes:

1. Memory leak in application

2. Processing too much data at once

3. Free tier limit (512 MB) exceeded

4. Large dependency tree

5. No garbage collection optimization

Fix Strategy:

Short-term fixes:

Node.js - Increase heap size (if on paid plan):

envVars:
  - key: NODE_OPTIONS
    value: --max-old-space-size=2048

Python - Optimize memory:

# Process data in chunks
for chunk in pd.read_csv('large_file.csv', chunksize=1000):
    process(chunk)

Long-term fixes:

1. Profile memory usage

2. Fix memory leaks

3. Optimize data structures

4. Upgrade to higher plan with more RAM

8. UNCAUGHT_EXCEPTION

Description: Unhandled error crashes the application.

Patterns to Match:

• UnhandledPromiseRejectionWarning

• Uncaught Error:

• Traceback (most recent call last):

• panic: runtime error:

• Fatal error:

Root Causes:

1. Missing error handling

2. Async errors not caught

3. Null pointer exceptions

4. Division by zero

Fix Strategy:

Node.js - Add error handlers:

// Catch all errors
process.on('uncaughtException', (err) => {
  console.error('Uncaught Exception:', err);
  process.exit(1);
});

process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection:', reason);
  process.exit(1);
});

// Express error handler
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ error: 'Internal server error' });
});

Python - Add try/catch:

try:
    # Your code
    result = risky_operation()
except Exception as e:
    logger.error(f"Error: {e}")
    # Handle gracefully

Build Errors

9. BUILD_TIMEOUT

Description: Build takes longer than allowed time.

Patterns to Match:

• Build timed out after 120 minutes

• Command timed out

• Build exceeded time limit

Root Causes:

1. Too many dependencies

2. Large dependency compilation (native modules)

3. Slow build scripts

4. Network issues downloading packages

Fix Strategy:

Optimize dependencies:

// Remove unused dependencies
{
  "dependencies": {
    // Only what you actually use
  }
}

Use faster build commands:

buildCommand: npm ci --prefer-offline && npm run build

If the build cannot complete within the 120-minute command limit, move expensive artifact generation to CI/CD or another build stage and deploy the resulting artifact or image.

10. DOCKER_BUILD_FAILED

Description: Docker image build fails.

Patterns to Match:

• failed to solve with frontend dockerfile.v0

• ERROR [internal] load metadata for

• failed to compute cache key

• COPY failed:

• RUN returned a non-zero code

Root Causes:

1. Invalid Dockerfile syntax

2. Base image not found

3. COPY source doesn't exist

4. RUN command fails

5. Build context too large

Fix Strategy:

Check Dockerfile:

# Use valid base image
FROM node:20-alpine

# Set working directory
WORKDIR /app

# Copy dependency files first
COPY package*.json ./
RUN npm ci

# Then copy source
COPY . .

# Build
RUN npm run build

# Expose port
EXPOSE 10000

# Start
CMD ["npm", "start"]

Add .dockerignore:

node_modules
.git
.env
*.log

Database Errors

11. DATABASE_MIGRATION_FAILED

Description: Database migration fails during build.

Patterns to Match:

• ProgrammingError: relation "users" already exists

• django.db.migrations.exceptions.InconsistentMigrationHistory

• Prisma migration failed

• Migration failed to apply

Root Causes:

1. Migration conflicts

2. Database already has schema

3. Migration dependencies missing

4. Database locked

Fix Strategy:

Django:

# Check migration status
python manage.py showmigrations

# Fake initial migration if schema exists
python manage.py migrate --fake-initial

Rails:

# Check schema exists
bundle exec rails db:migrate:status

# Reset if needed (CAUTION: data loss)
bundle exec rails db:reset

Prisma:

# Deploy migrations
npx prisma migrate deploy

# Or generate client only
npx prisma generate

Security & Permission Errors

12. PERMISSION_DENIED

Description: Application doesn't have permission to access resource.

Patterns to Match:

• EACCES: permission denied

• Error: EPERM: operation not permitted

• PermissionError: [Errno 13] Permission denied

Root Causes:

1. Trying to write to read-only filesystem

2. Wrong file permissions

3. Trying to bind to privileged port (<1024)

Fix Strategy:

Use allowed directories:

• /tmp - writable temporary storage

• /var - avoid, not writable

• Use environment variables for file paths

Use correct port:

envVars:
  - key: PORT
    value: 10000  # Use 10000, not 80 or 443

Dependency Version Errors

13. VERSION_MISMATCH

Description: Incompatible dependency versions.

Patterns to Match:

• npm ERR! peer dep missing

• npm ERR! ERESOLVE unable to resolve dependency tree

• Requires: Python >=3.8, but current version is 3.7

• requires Go version 1.20 or later

Fix Strategy:

Node.js - Fix peer dependencies:

npm install --legacy-peer-deps

Or update package.json:

{
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  }
}

Python - Specify version:

# runtime.txt
python-3.11.5

Go - Update go.mod:

go 1.21

Resource Errors

14. DISK_SPACE_EXCEEDED

Description: Running out of disk space during build or runtime.

Patterns to Match:

• No space left on device

• ENOSPC: no space left on device

• Disk quota exceeded

Root Causes:

1. Large build artifacts

2. Log files growing too large

3. Too many dependencies

Fix Strategy:

Clean build artifacts:

buildCommand: npm ci && npm run build && npm prune --production

Remove unnecessary files:

# In build command
rm -rf .git tests/ docs/

Networking Errors

15. EXTERNAL_API_TIMEOUT

Description: External API calls timing out.

Patterns to Match:

• ETIMEDOUT

• ESOCKETTIMEDOUT

• Request timeout

• connect ETIMEDOUT

Root Causes:

1. API endpoint down

2. Network issues

3. Timeout too short

4. Rate limiting

Fix Strategy:

Add retries and timeout:

const axios = require('axios');

const api = axios.create({
  timeout: 10000,
  retry: {
    retries: 3,
    retryDelay: (retryCount) => retryCount * 1000
  }
});

Quick Reference Matrix

Debugging Priority Order

1. Check environment variables first (Most common)

2. Verify port binding (Second most common)

3. Check build logs for errors

4. Verify database connections

5. Check for missing dependencies

6. Review application logs

7. Check resource usage

Exit Code Reference

Common exit codes and their meanings:

Note: Exit codes 128+N indicate the process was terminated by signal N. For example, 137 = 128 + 9 (SIGKILL).

Next Steps

After identifying error pattern:

1. Review troubleshooting.md for detailed fix procedures

2. Review log-analysis.md for log reading tips

3. Apply fix and monitor deployment