Common Deploy Errors on Vertra Cloud and How to Fix Them

This guide lists the most frequent errors when deploying on Vertra Cloud, in symptom → cause → fix format. If your application doesn’t come up, the reason is almost always one of these: insufficient memory (OOMKilled), a dependency missing from the manifest, a missing start script, or the server listening on localhost instead of 0.0.0.0.

Platform Errors

The errors below come from the platform, not your code: memory, container lifecycle, upload and plan limits.

Application not starting / Crashing

OOMKilled — Application killed for lack of memory

Symptom: The app stops with no error message, or Killed shows up in the logs.Cause: The app is using more RAM than what’s allocated.Fix:

Increase the allocated memory (try 50% more)
Java/JVM needs 512 MB+, apps with Puppeteer need 512 MB+
Optimize the code to reduce memory usage

Crash loop — Auto-restart disabled

Symptom: The app crashed 5 times in 10 minutes and auto-restart was disabled for 24 hours.Cause: A persistent error in the code (invalid token, missing dependency, syntax error).Fix:

Check the logs to identify the root error
Fix the issue and redeploy
Syntax errors and exit code 0 do NOT trigger auto-restart — the app simply stops

Application stops immediately (exit code 0)

Symptom: The app starts and stops right after, with no error.Cause: The process has nothing keeping it alive (no HTTP server, no logged-in bot, no event loop).Fix:

For bots: make sure the client is logging in (client.login(token))
For servers: make sure app.listen() is being called
Check that process.exit() isn’t being called accidentally

Deploy Errors

ZIP too large (max 100 MB)

Cause: Dependency directories included in the ZIP (node_modules, venv, .git, etc).Fix: Exclude these before zipping:

JS/TS: node_modules, .npm, .next, dist
Python: venv, .venv, __pycache__, .cache
Go: vendor | Rust: target | .NET: bin, obj | Elixir: _build, deps | Java: target, .gradle, build

Dependency installation exceeds the time limit (15 minutes)

Cause: Installing dependencies takes too long (too many packages, native compilation). Error: INSTALL_TIMEOUT.Fix:

Remove unnecessary dependencies
For large Node.js apps, consider running npm install locally and including only what’s needed

Build command fails or exceeds the time limit (10 minutes)

Cause: The build_command (the BUILD field in vertracloud.config) ended with an error (BUILD_FAILED) or didn’t finish in time (BUILD_TIMEOUT). It runs after dependency installation and before the application starts, in an environment with 2× the application’s RAM. A new application is still created, stopped, with the build output in its logs.Fix:

Run the command locally to see the real error
Simplify the build or increase the application’s memory (the build environment scales with it)

Deploys-per-hour limit reached

Cause: Creating an application, uploading a zip, deploying via GitHub, reinstalling dependencies, or changing the build command all count toward an hourly cap per account (20 on Starter 1 up to 60 on Pro and above). Error: DEPLOY_RATE_LIMITED.Fix:

Wait for the time indicated in details.retry_after
Restarting and stopping the application don’t count against this limit

Invalid ZIP structure

Cause: The ZIP has an extra folder wrapping the files (e.g. my-project/src/index.js instead of src/index.js).Fix: The files must be at the root of the ZIP, not inside an extra subfolder.

Network Errors

Site returns a timeout / Connection refused

Cause: The app is binding to localhost or 127.0.0.1 instead of 0.0.0.0.Fix:

app.listen(80, '0.0.0.0')

app.listen(80, 'localhost')
app.listen(80, '127.0.0.1')

Always use 0.0.0.0 as the host and the port configured in PORT.

Custom domain not working

Cause: DNS hasn’t propagated, the CNAME is wrong, or the plan doesn’t support it.Fix:

Confirm your plan is Starter 2 or above (custom domains)
Check that the CNAME record points to the address shown in the domain’s DNS records
On a root domain (example.com), your DNS provider must support CNAME flattening
A domain that stays without DNS for 14 days is removed automatically; delete its CNAME and TXT records at your DNS provider afterwards
DNS propagation can take up to 48 hours
SSL is provisioned automatically after validation

Database Errors

Connection refused / SSL required

Cause: Connecting without TLS, without the client certificate, or on the engine’s default port.Fix:

Download the three certificate files in the database’s Certificates tab
Pass the client certificate (.crt + .key) and use the .pem as the CA — every engine requires it
Use the database’s own port shown on its page — it’s not 5432, 27017, 6379 or 3306
For MongoDB, add authSource=admin to the URI
See How do I connect to each engine?

Too many open connections

Cause: Each connection consumes memory. Without connection pooling, connections pile up.Fix:

Use connection pooling in your database client
Reduce the number of simultaneous connections
Increase the database’s memory if needed

Platform Protections

Application paused by Vertra Shield

Symptom: Start/restart buttons disabled with a “Paused by Shield” banner and a countdown in the dashboard.Cause: Vertra Shield temporarily stopped the application after detecting traffic above the limits. The dashboard shows the reason and the remaining pause time, which can reach up to 1 hour. Shield only stops the application — it never deletes it, its files or its data.Fix:

Wait for the time shown in the dashboard before starting or restarting the application.
Review the code: look for infinite loops, unbounded recursive calls, or uncontrolled bulk requests.
Add rate limiting: implement per-IP or per-session request limits in your code.
Fix the cause before the pause ends: start, restart, deploy, configuration changes and deleting the application stay blocked until then, and repeated occurrences make the next pause longer.

Node.js / JavaScript

Cannot find module 'xxx' / MODULE_NOT_FOUND

Cause: The module isn’t in dependencies in package.json, or is only in devDependencies.Fix: Without a build command, the platform installs only dependencies; with one, it installs devDependencies too. If the package is needed at runtime, move it to dependencies:

npm install discord.js --save

npm ERR! missing script: start

Cause: package.json has no start script defined.Fix: Add to package.json:

{
  "scripts": {
    "start": "node index.js"
  }
}

Or set the START field in vertracloud.config.

SyntaxError: Cannot use import statement outside a module

Cause: Using import (ES Module) in a CommonJS project.Fix: Add to package.json:

{
  "type": "module"
}

Or convert to require().

ERR_REQUIRE_ESM — require() of ES Module not supported

Cause: Trying to use require() on a package that only supports ESM (e.g. node-fetch v3+, chalk v5+).Fix: Switch to ESM ("type": "module") or use an older version of the package (e.g. node-fetch@2).

ERESOLVE — unable to resolve dependency tree

Cause: Version conflict between dependencies (peer dependencies).Fix: Create a .npmrc file at the project root with:

legacy-peer-deps=true

Error: listen EADDRINUSE

Cause: The port is already in use, or the app tries to bind twice.Fix: Make sure there’s only one app.listen() in the code. Use the environment’s PORT variable.

Could not locate the bindings file (better-sqlite3)

Cause: Native modules compiled on macOS/Windows don’t work in the Linux container.Fix: Don’t include node_modules/ in the upload. The platform compiles native modules for Linux automatically.

TypeScript

tsx / ts-node: command not found

Cause: The TypeScript runtime isn’t in the dependencies.Fix: Add tsx or ts-node to dependencies:

npm install tsx --save

TSError: Unable to compile TypeScript

Cause: TypeScript compilation errors that didn’t show up locally, or a missing tsconfig.json.Fix: Include tsconfig.json in the upload. Fix all TS errors locally before deploying. Consider pre-compiling and uploading dist/.

Python

ModuleNotFoundError: No module named 'xxx'

Cause: The module isn’t in requirements.txt.Fix: Generate the file with:

pip freeze > requirements.txt

Make sure it’s at the project root.

requirements.txt not found

Cause: The file is missing, has the wrong name, or has a double extension (.txt.txt — common on Windows).Fix: Check the file’s exact name. On Windows, enable “show file extensions” to verify.

SyntaxError: invalid syntax

Cause: The code uses features from a newer Python version than the one selected (e.g. match/case from 3.10 on runtime 3.9).Fix: Select the correct Python version in the configuration. Use VERSION=recommended for the latest stable version.

UnicodeDecodeError / Encoding errors

Cause: Files with non-UTF-8 characters, or the container’s locale isn’t configured.Fix: Save all files as UTF-8. Use encoding='utf-8' when opening files:

with open('file.txt', 'r', encoding='utf-8') as f:
    ...

Flask/Django not accessible externally

Cause: Using the development server, which binds to 127.0.0.1.Fix: Use Gunicorn for production:

START=gunicorn app:app --bind 0.0.0.0:80

Never use the Flask/Django development server in production.

Go

go.mod not found / cannot find main module

Cause: go.mod is missing from the project root.Fix:

go mod init module-name
go mod tidy

Include go.mod and go.sum in the upload.

Build fails / Incompatible binary

Cause: The binary was compiled for macOS/Windows, not Linux.Fix: If uploading source code, include go.mod and go.sum. If uploading a binary, compile it for Linux:

GOOS=linux GOARCH=amd64 go build -o app main.go

Java

no main manifest attribute, in app.jar

Cause: The JAR has no Main-Class in MANIFEST.MF.Fix: Configure the build tool to produce a fat JAR. For Maven, use maven-shade-plugin or spring-boot-maven-plugin.

OutOfMemoryError: Java heap space

Cause: The JVM heap exceeds the memory allocated to the container.Fix: Java apps need 512 MB+. Limit the heap:

START=java -Xmx256m -Xms128m -jar app.jar

PHP

Dependencies not installed / composer.json not found

Cause: composer.json is missing from the root, or vendor/ was uploaded (which may be incompatible).Fix: Include composer.json and composer.lock at the root. Don’t upload the vendor/ directory.

Discord Bots

An invalid token was provided / Improper token

Cause: The bot token is invalid, expired, or was regenerated.Fix:

Generate a new token in the Discord Developer Portal
Set it as an environment variable (don’t hardcode it in the code)
Restart the application after updating it

Used disallowed intents / DisallowedIntents

Cause: The bot uses privileged intents that aren’t enabled in the Developer Portal.Fix: Discord Developer Portal → Bot → Privileged Gateway Intents → Enable:

Message Content Intent (to read message content)
Server Members Intent (for member events)
Presence Intent (for presence status)

Valid intents must be provided / ClientMissingIntents

Cause: No intent was specified when creating the client.Fix:

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent
  ]
});

Bot goes offline randomly

Cause: Insufficient memory causing a kill, or an outdated discord.js/discord.py version.Fix:

Increase the allocated memory
Update discord.js/discord.py to the latest version
Check for memory leaks

on_message doesn't work (discord.py)

Cause: The message_content intent is missing (required since discord.py 2.0+).Fix:

intents = discord.Intents.default()
intents.message_content = True
client = discord.Client(intents=intents)

Also enable it in the Developer Portal.

Environment Variables

undefined / null values in the configuration

Cause: Environment variables weren’t configured on the platform.Fix: Configure all variables via the dashboard or API. Never hardcode sensitive values. Use a .env.example to document which variables are required.

.env file doesn't work on the platform

Cause: The platform doesn’t read .env files automatically.Fix: Configure the variables through the Vertra Cloud dashboard (Environment Variables tab) or via the API. Don’t rely on dotenv loading from a .env file in production.

Introduction

Deploy

Troubleshooting

Common Deploy Errors on Vertra Cloud and How to Fix Them

Platform Errors

Application not starting / Crashing

Deploy Errors

Network Errors

Database Errors

Platform Protections

Node.js / JavaScript

TypeScript

Python

Go

Java

PHP

Discord Bots

Environment Variables

​Platform Errors

​Application not starting / Crashing

​Deploy Errors

​Network Errors

​Database Errors

​Platform Protections

​Node.js / JavaScript

​TypeScript

​Python

​Go

​Java

​PHP

​Discord Bots

​Environment Variables

Platform Errors

Application not starting / Crashing

Deploy Errors

Network Errors

Database Errors

Platform Protections

Node.js / JavaScript

TypeScript

Python

Go

Java

PHP

Discord Bots

Environment Variables