Troubleshooting Your Deploy

Language version

Render sets a default language version for each native runtime. This default likely differs from the exact language version you use locally.

For all native runtimes besides Go, you can specify an exact language version to use. See details for each runtime:

• Node.js
• Python
• Ruby
• Elixir/Erlang
• Rust

Dependency versions

Render might be using a different version of your app's dependencies than you use locally.

Perform a fresh install of your project on your local machine to confirm that you're using exactly the dependency versions specified in your repository (such as in your package-lock.json file).

Invalid build command

Make sure the build command matches the command you use to build your app locally. Common examples include:

• npm install (Node.js)
• pip install -r requirements.txt (Python)

Invalid pre-deploy command

If you've set a pre-deploy command, make sure it's valid as well. Common examples include:

• bundle exec rails db:migrate (Ruby)
• python manage.py migrate (Python)

Invalid Git provider credentials

If your Git provider credentials are expired or otherwise invalid, Render can't access your repository to pull the latest version of your app.

Verify your Git deployment credentials. If they're missing or no longer valid, replace them.

Missing or incorrect environment variables

On your local machine, your app might read environment variables from a .env file. On Render, you instead set these environment variables on your service's Environment page in the Render Dashboard. Make sure that page reflects all of the environment variables your app needs to build and start successfully.

If you're using Blueprints, you can also add environment variables to your service's Blueprint file. Do not hardcode sensitive values in your Blueprint file.

Missing build tool

Any tool invoked by your build command must be available in Render's build environment. For a list of available and commonly used tools, see Tools and utilities.

If the build environment doesn't include a tool or dependency your app needs, you can install it as a preliminary step in your build command.

Module Not Found or ModuleNotFoundError

Usually indicates one of the following:

• A referenced dependency was not found (e.g., in your package.json or requirements.txt file).
• A referenced file (such as app.js or app.py) was not found at a specified location.
• If you're developing on Windows or another platform with a case-insensitive filesystem, make sure that all file paths, names, and extensions are cased correctly.
  • You might need to check the contents of your Git repo directly.

SyntaxError: Unexpected token '??='

The app's Node.js version doesn't support the indicated operator or method.

The engine "node" is incompatible with this module. Expected version…

The app's Node.js version doesn't work with the specified module.

requires Python >= 3.8

A dependency isn't compatible with the app's Python version.

Build Minutes Exhausted

Your workspace used all of its monthly build pipeline minutes.

To resume builds, raise your spend limit or wait for next month's refresh.

Out of memory

Your build exceeded its available memory.

For details on memory limits while building, see Pipeline tiers.

Exited with status <N>

Your application exited or crashed while building.

See the exit code to identify the cause.

Timed out

Your build did not finish within the allowed time.

Check your logs for slow dependency installation, network requests, or stalled commands.

Invalid start command

Make sure your start command is valid. This usually matches the command you use to start your app locally. Common examples include:

• npm start (Node.js)
• gunicorn myapp:app (Python)

Missing Dockerfile CMD or ENTRYPOINT

If you're building from a Dockerfile, make sure that your Dockerfile includes the CMD or ENTRYPOINT directive (or both).

If you omit both of these directives, your deploy might appear to hang in the Render Dashboard.

Misconfigured health checks

For web and private services, a new instance only starts receiving requests after it starts up successfully and passes health checks.

For details, see Health check errors.

Port scan timeout reached

Render failed to detect at least one open port on your service's host before its scan timed out. This error is specific to web services and private services.

Common causes include:

• Your service does not bind to any ports.
  • If your service intentionally does not bind to any ports, create a background worker instead of a web service or private service.
• Your web service binds to the wrong host and port.
  • Bind your HTTP server to 0.0.0.0 and the port specified by the PORT environment variable (defaults to 10000).
  • Render doesn't support IPv6 addresses.
• Render's port scan timed out before your service started listening on a port.
  • Keep your start command simple and defer any non-essential work until after your server starts listening.
  • Make sure to bind your host and port as early as possible in your application code.
• Your service has conflicting port bindings.
  • If your start command creates a server listening on a port, don't start another listener in your application code.

Out of memory

Your instance ran out of memory during startup. See Memory exhaustion.

Exited with status <N>

Your application exited or crashed during startup.

See the exit code to identify the cause.

Timed out

Your instance was not ready before the deploy timed out. Common causes include:

• Slow or blocking database queries or third-party API calls.
• Slow or failing custom health checks.
• CPU exhaustion, which can slow your service's startup.

Image Pull Failed

Render couldn't pull your image from the external registry. For details, see Image pull failures.

HTTP health check failed (timed out after 5 seconds)

Your health check timed out.

Check your instance's CPU and RAM usage to confirm you're not experiencing memory or CPU exhaustion.

We recommend a simple health check, such as a basic database query, to avoid the check itself timing out.

HTTP health check failed with status code <N>

Your health check endpoint returned a status code outside the 2xx to 3xx range.

Send a request to the endpoint and confirm the returned status code is healthy. Check your logs to see if there are HTTP error codes.

Increased traffic

If your instance's memory usage spikes with increases in inbound traffic, consider scaling your service.

Memory leak

Memory usage that climbs steadily until the instance crashes typically indicates a leak.

Memory leaks are usually caused by a code or configuration issue. If the pattern started after a specific deploy, try rolling back to a version from before the issue started.

WEB_CONCURRENCY is too high (Python or Ruby)

Render can set a default WEB_CONCURRENCY environment variable based on your instance's available CPU.

If the default concurrency is too high for your app, your instance might run out of memory. Set a lower concurrency to reduce memory pressure.

JVM-based apps deployed via Docker

By default, apps written in Java, Kotlin, and Scala are memory-intensive.

We recommend upgrading your service to the 1c-2g compute plan or higher.

Node.js AI workflow tools

Tools such as n8n and Flowise are memory-intensive by default.

We recommend upgrading your service to the 1c-2g compute plan or higher.

Node.js heap limit too low

If your instance logs JavaScript heap out of memory errors, Node's heap limit might be lower than your instance's available memory.

Set --max-old-space-size=<megabytes> lower than your instance's available memory.

For example, if your instance has 4 GB of RAM, you'd set --max-old-space-size=3584. For additional examples, see this Stack Overflow discussion.

Application memory usage

If your instance’s memory usage spikes without a corresponding increase in inbound traffic, your application's behavior (such as background work, caching, or memory retention) might be contributing.

Add logging or monitoring to track memory usage and help identify when spikes occur. For complex issues, consider using an Application Performance Monitor (APM).

Increased or spiking traffic

If your instance's CPU usage climbs with sustained increases in inbound traffic, consider scaling your service.

For sudden traffic spikes, run load tests with burst-like traffic to choose a compute plan that handles your service's peak demand without exceeding limits.

Stuck workers or threads

Long-running database queries and API calls can reduce throughput and spike CPU usage from retries.

Keep workers from becoming overloaded by:

• Setting explicit dependency timeouts to prevent stuck requests (e.g., the Gunicorn timeout parameter).
• Using horizontal scaling to increase your service's request capacity.
• Adjusting your app's concurrency settings so each instance handles a manageable number of requests at once.
  • For Ruby and Python services, you can set this with the WEB_CONCURRENCY environment variable.

Inefficient Postgres queries

Slow queries, lock contention, or missing indexes can increase your Postgres instance's CPU usage.

See PostgreSQL performance troubleshooting.

Concurrent one-off jobs

Running too many one-off jobs at once can cause your instance's CPU usage to spike.

Trigger jobs in smaller, staggered batches to reduce peak CPU demand.