> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Errores comunes de despliegue en Vertra Cloud y cómo solucionarlos

> Síntoma, causa y solución de los errores de despliegue más frecuentes en Vertra Cloud: OOMKilled, crash loop, módulo ausente, timeout y token no válido.

Esta guía enumera los errores más frecuentes al desplegar en Vertra Cloud, en formato síntoma → causa →
solución. Si tu aplicación no arranca, el motivo casi siempre es uno de estos: memoria insuficiente
(OOMKilled), una dependencia que falta en el manifiesto, un script de inicio ausente o el servidor
escuchando en `localhost` en lugar de `0.0.0.0`.

## Errores de la plataforma

Los errores de esta sección proceden de la plataforma, no de tu código: memoria, ciclo de vida del
contenedor, subida de archivos y límites del plan.

### La aplicación no arranca / se cae

> **OOMKilled — Aplicación terminada por falta de memoria**
>
> **Síntoma:** La aplicación se detiene sin ningún mensaje de error, o aparece `Killed` en los logs.
>
> **Causa:** La aplicación usa más RAM de la que tiene asignada.
>
> **Solución:**
>
> * Aumenta la memoria asignada (prueba con un 50 % más)
> * Java/JVM necesita 512 MB o más, y las aplicaciones con Puppeteer también necesitan 512 MB o más
> * Optimiza el código para reducir el uso de memoria

> **Crash loop — reinicio automático desactivado**
>
> **Síntoma:** La aplicación se cayó 5 veces en 10 minutos y el reinicio automático se desactivó durante 24 horas.
>
> **Causa:** Un error persistente en el código (token no válido, dependencia ausente, error de sintaxis).
>
> **Solución:**
>
> * Revisa los logs para identificar el error de origen
> * Corrige el problema y vuelve a desplegar
> * Los errores de sintaxis y las salidas con código 0 NO activan el reinicio automático: la aplicación simplemente se detiene

> **La aplicación se detiene de inmediato (código de salida 0)**
>
> **Síntoma:** La aplicación arranca y se detiene justo después, sin ningún error.
>
> **Causa:** No hay nada que mantenga vivo el proceso (ningún servidor HTTP, ningún bot con sesión iniciada, ningún event loop).
>
> **Solución:**
>
> * En bots: asegúrate de que el cliente inicie sesión (`client.login(token)`)
> * En servidores: asegúrate de que se llame a `app.listen()`
> * Comprueba que `process.exit()` no se esté llamando por error

### Errores de despliegue

> **ZIP demasiado grande (máximo 100 MB)**
>
> **Causa:** Se incluyen en el ZIP directorios de dependencias (`node_modules`, `venv`, `.git`, etc).
>
> **Solución:** Excluye estos elementos antes de comprimir:
>
> * **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`

> **La instalación de dependencias supera el límite de tiempo (15 minutos)**
>
> **Causa:** Instalar las dependencias tarda demasiado (demasiados paquetes, compilación nativa). Error: `INSTALL_TIMEOUT`.
>
> **Solución:**
>
> * Elimina las dependencias innecesarias
> * En aplicaciones Node.js grandes, considera ejecutar `npm install` en local e incluir solo lo necesario

> **El comando de build falla o supera el límite de tiempo (10 minutos)**
>
> **Causa:** El `build_command` (el campo `BUILD` de `vertracloud.config`) terminó con un error
> (`BUILD_FAILED`) o no acabó a tiempo (`BUILD_TIMEOUT`). Se ejecuta después de instalar las dependencias
> y antes de que la aplicación arranque, en un entorno con 2× la RAM de la aplicación. Una aplicación nueva
> se sigue creando, detenida, con la salida del build en sus logs.
>
> **Solución:**
>
> * Ejecuta el comando en local para ver el error real
> * Simplifica el build o aumenta la memoria de la aplicación (el entorno de build escala con ella)

> **Límite de despliegues por hora alcanzado**
>
> **Causa:** Crear una aplicación, subir un ZIP, desplegar desde GitHub, reinstalar dependencias o cambiar el
> comando de build cuentan para un límite por hora por cuenta (de 10 en Economy hasta 60 en Intermediary y en
> cualquier nivel Enterprise). Error: `DEPLOY_RATE_LIMITED`.
>
> **Solución:**
>
> * Espera el tiempo indicado en `details.retry_after`
> * Reiniciar y detener la aplicación no cuentan para este límite

> **Estructura de ZIP no válida**
>
> **Causa:** El ZIP tiene una carpeta extra que envuelve los archivos (por ejemplo, `my-project/src/index.js` en lugar de `src/index.js`).
>
> **Solución:** Los archivos deben estar en la raíz del ZIP, no dentro de una subcarpeta extra.

### Errores de red

> **El sitio devuelve timeout / Connection refused**
>
> **Causa:** La aplicación escucha en `localhost` o `127.0.0.1` en lugar de `0.0.0.0`.
>
> **Solución:**
>
> ```js theme={null}
> app.listen(80, '0.0.0.0')
>
> app.listen(80, 'localhost')
> app.listen(80, '127.0.0.1')
> ```
>
> Usa siempre `0.0.0.0` como host y el puerto configurado en `PORT`.

> **El dominio personalizado no funciona**
>
> **Causa:** El DNS todavía no se ha propagado, el CNAME es incorrecto o el plan no lo admite.
>
> **Solución:**
>
> * Confirma que tu plan es Intermediary o superior (dominios personalizados)
> * Comprueba que el registro CNAME apunta a la dirección que aparece en **Registros DNS** del dominio
> * En un dominio raíz (`example.com`), tu proveedor de DNS debe admitir CNAME flattening
> * Un dominio que permanezca sin DNS durante 14 días se elimina automáticamente; después, borra sus registros `CNAME` y `TXT` en tu proveedor de DNS
> * La propagación del DNS puede tardar hasta 48 horas
> * El SSL se provisiona automáticamente después de la validación

### Errores de base de datos

> **Connection refused / SSL required**
>
> **Causa:** Conexión sin TLS, sin el certificado de cliente o usando el puerto por defecto del motor.
>
> **Solución:**
>
> * Descarga los tres archivos de certificado en la pestaña **Certificados** de la base de datos
> * Pasa el certificado de cliente (`.crt` + `.key`) y usa el `.pem` como CA: todos los motores lo exigen
> * Usa el puerto propio de la base de datos que aparece en su página; no es 5432, 27017, 6379 ni 3306
> * En MongoDB, añade `authSource=admin` a la URI
> * Consulta [¿Cómo me conecto a cada motor?](https://docs.vertracloud.app/es-es/databases.md#cómo-me-conecto-a-cada-motor)

> **Demasiadas conexiones abiertas**
>
> **Causa:** Cada conexión consume memoria. Sin pool de conexiones, las conexiones se acumulan.
>
> **Solución:**
>
> * Usa connection pooling en tu cliente de base de datos
> * Reduce el número de conexiones simultáneas
> * Aumenta la memoria de la base de datos si hace falta

### Protecciones de la plataforma

> **Aplicación pausada por Vertra Shield**
>
> **Síntoma:** Los botones de iniciar y reiniciar aparecen desactivados, con un aviso "Pausada por Vertra Shield" y una cuenta atrás en el panel.
>
> **Causa:** Vertra Shield detuvo temporalmente la aplicación tras detectar tráfico por encima de los límites. El panel muestra el motivo y el tiempo de pausa restante, que puede llegar a 1 hora. Shield solo detiene la aplicación: nunca la elimina, ni elimina sus archivos o sus datos.
>
> **Solución:**
>
> * **Espera el tiempo que muestra el panel** antes de iniciar o reiniciar la aplicación.
> * **Revisa el código:** busca bucles infinitos, llamadas recursivas sin límite o peticiones masivas sin control.
> * **Añade rate limiting:** implementa límites de peticiones por IP o por sesión en tu código.
> * **Corrige la causa antes de que termine la pausa:** iniciar, reiniciar, desplegar, cambiar la configuración y eliminar la aplicación siguen bloqueados hasta entonces, y las repeticiones alargan la siguiente pausa.

***

## Node.js / JavaScript

> **Cannot find module 'xxx' / MODULE\_NOT\_FOUND**
>
> **Causa:** El módulo no está en `dependencies` del `package.json`, o solo está en `devDependencies`.
>
> **Solución:** Sin un comando de build, la plataforma solo instala `dependencies`; con uno, instala también `devDependencies`. Si el paquete se necesita en tiempo de ejecución, muévelo a `dependencies`:
>
> ```bash theme={null}
> npm install discord.js --save
> ```

> **npm ERR! missing script: start**
>
> **Causa:** El `package.json` no tiene definido ningún script `start`.
>
> **Solución:** Añade al `package.json`:
>
> ```json theme={null}
> {
>   "scripts": {
>     "start": "node index.js"
>   }
> }
> ```
>
> O define el campo `START` en `vertracloud.config`.

> **SyntaxError: Cannot use import statement outside a module**
>
> **Causa:** Se usa `import` (ES Module) en un proyecto CommonJS.
>
> **Solución:** Añade al `package.json`:
>
> ```json theme={null}
> {
>   "type": "module"
> }
> ```
>
> O convierte el código a `require()`.

> **ERR\_REQUIRE\_ESM — require() of ES Module not supported**
>
> **Causa:** Se intenta usar `require()` con un paquete que solo admite ESM (por ejemplo, `node-fetch` v3+, `chalk` v5+).
>
> **Solución:** Cambia a ESM (`"type": "module"`) o usa una versión anterior del paquete (por ejemplo, `node-fetch@2`).

> **ERESOLVE — unable to resolve dependency tree**
>
> **Causa:** Conflicto de versiones entre dependencias (peer dependencies).
>
> **Solución:** Crea un archivo `.npmrc` en la raíz del proyecto con:
>
> ```
> legacy-peer-deps=true
> ```

> **Error: listen EADDRINUSE**
>
> **Causa:** El puerto ya está en uso, o la aplicación intenta escuchar dos veces.
>
> **Solución:** Asegúrate de que solo haya un `app.listen()` en el código. Usa la variable `PORT` del entorno.

> **Could not locate the bindings file (better-sqlite3)**
>
> **Causa:** Los módulos nativos compilados en macOS/Windows no funcionan en el contenedor Linux.
>
> **Solución:** No incluyas `node_modules/` en la subida. La plataforma compila automáticamente los módulos nativos para Linux.

***

## TypeScript

> **tsx / ts-node: command not found**
>
> **Causa:** El runtime de TypeScript no está en las dependencias.
>
> **Solución:** Añade `tsx` o `ts-node` a `dependencies`:
>
> ```bash theme={null}
> npm install tsx --save
> ```

> **TSError: Unable to compile TypeScript**
>
> **Causa:** Errores de compilación de TypeScript que no aparecieron en local, o un `tsconfig.json` ausente.
>
> **Solución:** Incluye `tsconfig.json` en la subida. Corrige todos los errores de TS en local antes de desplegar. Considera precompilar y subir `dist/`.

***

## Python

> **ModuleNotFoundError: No module named 'xxx'**
>
> **Causa:** El módulo no está en `requirements.txt`.
>
> **Solución:** Genera el archivo con:
>
> ```bash theme={null}
> pip freeze > requirements.txt
> ```
>
> Asegúrate de que esté en la raíz del proyecto.

> **requirements.txt no encontrado**
>
> **Causa:** El archivo falta, tiene un nombre incorrecto o tiene una doble extensión (`.txt.txt`, habitual en Windows).
>
> **Solución:** Revisa el nombre exacto del archivo. En Windows, activa "mostrar extensiones de archivo" para comprobarlo.

> **SyntaxError: invalid syntax**
>
> **Causa:** El código usa funciones de una versión de Python más nueva que la seleccionada (por ejemplo, `match/case` de 3.10 en el runtime 3.9).
>
> **Solución:** Selecciona la versión correcta de Python en la configuración. Usa `VERSION=recommended` para la última versión estable.

> **UnicodeDecodeError / Errores de codificación**
>
> **Causa:** Archivos con caracteres que no son UTF-8, o el locale del contenedor no está configurado.
>
> **Solución:** Guarda todos los archivos en UTF-8. Usa `encoding='utf-8'` al abrir archivos:
>
> ```python theme={null}
> with open('file.txt', 'r', encoding='utf-8') as f:
>     ...
> ```

> **Flask/Django no accesible desde el exterior**
>
> **Causa:** Se usa el servidor de desarrollo, que escucha en `127.0.0.1`.
>
> **Solución:** Usa Gunicorn en producción:
>
> ```
> START=gunicorn app:app --bind 0.0.0.0:80
> ```
>
> Nunca uses el servidor de desarrollo de Flask/Django en producción.

***

## Go

> **go.mod not found / cannot find main module**
>
> **Causa:** `go.mod` no está en la raíz del proyecto.
>
> **Solución:**
>
> ```bash theme={null}
> go mod init module-name
> go mod tidy
> ```
>
> Incluye `go.mod` y `go.sum` en la subida.

> **El build falla / Binario incompatible**
>
> **Causa:** El binario se compiló para macOS/Windows, no para Linux.
>
> **Solución:** Si subes código fuente, incluye `go.mod` y `go.sum`. Si subes un binario, compílalo para Linux:
>
> ```bash theme={null}
> GOOS=linux GOARCH=amd64 go build -o app main.go
> ```

***

## Java

> **no main manifest attribute, in app.jar**
>
> **Causa:** El JAR no tiene `Main-Class` en MANIFEST.MF.
>
> **Solución:** Configura la herramienta de build para generar un fat JAR. En Maven, usa `maven-shade-plugin` o `spring-boot-maven-plugin`.

> **OutOfMemoryError: Java heap space**
>
> **Causa:** El heap de la JVM supera la memoria asignada al contenedor.
>
> **Solución:** Las aplicaciones Java necesitan 512 MB o más. Limita el heap:
>
> ```
> START=java -Xmx256m -Xms128m -jar app.jar
> ```

***

## PHP

> **Dependencias no instaladas / composer.json no encontrado**
>
> **Causa:** `composer.json` falta en la raíz, o se subió `vendor/` (que puede ser incompatible).
>
> **Solución:** Incluye `composer.json` y `composer.lock` en la raíz. No subas el directorio `vendor/`.

***

## Bots de Discord

> **An invalid token was provided / Improper token**
>
> **Causa:** El token del bot no es válido, ha caducado o se ha regenerado.
>
> **Solución:**
>
> * Genera un token nuevo en el [Discord Developer Portal](https://discord.com/developers/applications)
> * Guárdalo como variable de entorno (no lo escribas fijo en el código)
> * Reinicia la aplicación después de actualizarlo

> **Used disallowed intents / DisallowedIntents**
>
> **Causa:** El bot usa intents privilegiados que no están activados en el Developer Portal.
>
> **Solución:** Discord Developer Portal → Bot → Privileged Gateway Intents → activa:
>
> * **Message Content Intent** (para leer el contenido de los mensajes)
> * **Server Members Intent** (para eventos de miembros)
> * **Presence Intent** (para el estado de presencia)

> **Valid intents must be provided / ClientMissingIntents**
>
> **Causa:** No se especificó ningún intent al crear el cliente.
>
> **Solución:**
>
> ```js theme={null}
> const client = new Client({
>   intents: [
>     GatewayIntentBits.Guilds,
>     GatewayIntentBits.GuildMessages,
>     GatewayIntentBits.MessageContent
>   ]
> });
> ```

> **El bot se desconecta de forma aleatoria**
>
> **Causa:** Memoria insuficiente que provoca un cierre, o una versión desactualizada de discord.js/discord.py.
>
> **Solución:**
>
> * Aumenta la memoria asignada
> * Actualiza discord.js/discord.py a la última versión
> * Busca fugas de memoria

> **on\_message no funciona (discord.py)**
>
> **Causa:** Falta el intent `message_content` (obligatorio desde discord.py 2.0+).
>
> **Solución:**
>
> ```python theme={null}
> intents = discord.Intents.default()
> intents.message_content = True
> client = discord.Client(intents=intents)
> ```
>
> Actívalo también en el Developer Portal.

***

## Variables de entorno

> **Valores undefined / null en la configuración**
>
> **Causa:** Las variables de entorno no se configuraron en la plataforma.
>
> **Solución:** Configura todas las variables desde el panel o la API. Nunca escribas valores sensibles en el código. Usa un `.env.example` para documentar qué variables son obligatorias.

> **El archivo .env no funciona en la plataforma**
>
> **Causa:** La plataforma no lee los archivos `.env` automáticamente.
>
> **Solución:** Configura las variables desde el panel de Vertra Cloud (pestaña **Variables de Entorno**) o mediante la API. No dependas de que `dotenv` cargue un archivo `.env` en producción.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.