'Cannot find module' y 'ModuleNotFoundError' en el deploy

Tu app arrancaba bien en tu computadora, hiciste el deploy y el log termina con uno de estos mensajes:

Error: Cannot find module 'express'
Require stack:
- /app/index.js
    at Module._resolveFilename (node:internal/modules/cjs/loader:1517:15)
    ...
    at Module._compile (node:internal/modules/cjs/loader:1871:14) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [ '/app/index.js' ]
}

ModuleNotFoundError: No module named 'discord'

Los dos mensajes dicen lo mismo: un import o require nombró algo que el runtime no pudo localizar. El arreglo casi nunca es un misterio, pero tienes que leer el mensaje antes de adivinar. El nombre entre comillas te dice cuál de las dos familias de problema tienes.

¿Qué significan realmente estos errores?#

En Node.js, require() lanza MODULE_NOT_FOUND cuando la ruta o el paquete no existe. La versión de ES modules, import, lanza ERR_MODULE_NOT_FOUND. En Python, ModuleNotFoundError es una subclase de ImportError, que se lanza cuando no se pudo localizar un módulo (documentación de Python).

Esta es la forma de ES modules, para un paquete que falta y para un archivo relativo:

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'express' imported from /app/index.js

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/app/utils' imported from /app/index.js
Did you mean to import "./utils.js"?

Fíjate en cómo es el nombre:

• Un nombre simple (express, discord): un paquete que no está instalado donde se ejecuta la app.
• Una ruta (./utils, /app/utils): un archivo que el runtime no encontró en esa ubicación exacta.

Todo lo que sigue parte de esa división.

¿Falta el paquete en las dependencias?#

Es la causa más común. Para un nombre de paquete simple, Node.js empieza en la carpeta del archivo actual, busca en node_modules y luego sube por las carpetas padre hasta la raíz del sistema de archivos (documentación de Node.js). Si ningún node_modules de ese camino contiene el paquete, aparece el error.

Revisa esto en orden:

1. ¿Está en package.json? Si lo instalaste con npm install express, aparece en la lista. Si copiaste código de un tutorial y nunca lo instalaste, no está.
2. ¿Está solo en devDependencies? npm indica que dependencies es para los paquetes de runtime y devDependencies para herramientas que los usuarios de tu módulo no necesitan, como frameworks de pruebas y transpiladores (documentación de npm). Una instalación de producción puede omitir los paquetes de desarrollo, y npm ci los omite por defecto cuando NODE_ENV es production (documentación de npm). Si tu app lo importa en runtime, muévelo:

npm install --save-prod express

3. ¿La instalación se ejecutó de verdad en el servidor? Subir la carpeta node_modules de tu PC no es fiable. Envía package.json junto con el lockfile e instala a partir de ellos.

npm ci es el comando correcto para una instalación limpia. Exige un package-lock.json existente, borra cualquier node_modules que haya y termina con error, en lugar de actualizar el lockfile, cuando package.json y el lockfile no coinciden. Ese último comportamiento es útil: convierte una diferencia silenciosa en un fallo visible.

npm ci
node index.js

Si npm ci falla porque el lockfile no está sincronizado, ejecuta npm install en local, haz commit del lockfile actualizado y vuelve a hacer el deploy.

¿La ruta, las mayúsculas o la extensión están mal?#

Cuando el nombre es una ruta, la causa es un archivo que no está donde el import dice.

Mayúsculas y minúsculas. En Linux, ./Utils.js y ./utils.js son dos archivos distintos. Los sistemas de archivos de Windows y macOS normalmente ignoran esa diferencia, así que un import con las mayúsculas equivocadas funciona en tu máquina y falla en el servidor. Renombra el archivo o corrige el import para que coincidan exactamente. Si solo cambias las mayúsculas del nombre de un archivo, asegúrate de que tu cliente de Git registre el cambio, porque algunas configuraciones lo ignoran.

Falta la extensión en ES modules. Con import, los especificadores relativos necesitan la extensión, y los índices de directorio deben indicarse completos (documentación de ESM de Node.js). Esto funciona con require en CommonJS, pero no con import:

// Falla en un ES module: ERR_MODULE_NOT_FOUND
import { helper } from "./utils";

// Funciona
import { helper } from "./utils.js";
import { setup } from "./startup/index.js";

Tu app es un ES module cuando package.json tiene "type": "module" o el archivo termina en .mjs. Si usas TypeScript con un bundler en local, los imports sin extensión pueden funcionar ahí y romperse cuando ejecutas la salida directamente.

Un archivo que nunca se subió. Comprueba que el archivo está en tu ZIP o en tu commit. Los culpables habituales son una línea del .gitignore o una subida que se saltó una carpeta. En un monorepo, un paquete compartido que está fuera de la carpeta que desplegaste también faltará.

¿El archivo principal o la salida del build están mal?#

Algunos proyectos compilan a una carpeta dist o build. Si tu comando de inicio apunta a dist/index.js y el paso de build nunca se ejecutó, o dist está ignorada por el control de versiones, falta el propio punto de entrada:

Error: Cannot find module '/app/dist/index.js'

Confirma tres cosas: el comando de build se ejecuta antes del de inicio, la carpeta de salida forma parte de lo que despliegas (o se genera en el servidor) y el archivo principal de tu configuración coincide con la ruta real. Revisa también "main" en package.json si importas el paquete por su nombre, porque un main ausente o que no se puede resolver, sin un index.js, hace que Node.js informe que falta el módulo entero (documentación de Node.js).

¿Por qué Python dice "No module named"?#

La versión de Python tiene sus propias causas.

El paquete no está instalado. Instálalo y regístralo para que el siguiente entorno también lo tenga:

python -m pip install discord.py
python -m pip freeze > requirements.txt

Después, en el destino, python -m pip install -r requirements.txt. La documentación de pip describe este flujo de freeze e instalación, y también aclara que pip freeze no calcula un lockfile ni el resultado de un solver (documentación de pip). Para fijar todo por completo, usa una herramienta de lockfile.

El nombre del import difiere del nombre de instalación. Esto confunde a mucha gente:

Intérprete equivocado. pip y python pueden pertenecer a instalaciones distintas. Usa python -m pip install ... para que el paquete vaya al intérprete que ejecutará tu código. Dentro de un entorno virtual, actívalo primero.

Un archivo local oculta el módulo o no coincide con él. Un archivo llamado discord.py o random.py en tu proyecto puede ocultar el paquete real. Para tus propios módulos, comprueba que la estructura de carpetas coincide con el import y que ejecutas la app desde el directorio de trabajo esperado.

¿Cómo diagnosticarlo rápido?#

Empieza por el mensaje:

1. Copia el nombre exacto del módulo del log.
2. ¿Nombre simple? Ejecuta npm ls express (Node.js) o python -m pip show discord.py (Python) en el mismo entorno que ejecuta la app.
3. ¿Ruta? Lista la carpeta y compara el nombre carácter por carácter, incluidas mayúsculas y extensión.
4. ¿Sigue sin funcionar? Ejecuta el import que falla de forma aislada:

node -e "require.resolve('express')"
node --input-type=module -e "await import('express')"
python -c "import discord; print(discord.__file__)"

require.resolve lanza MODULE_NOT_FOUND cuando no encuentra el módulo, así que muestra lo que ve el runtime sin arrancar toda tu app.

Un caso más de Node.js: require() solo puede cargar un ES module si no tiene await de nivel superior; si lo tiene, lanza ERR_REQUIRE_ASYNC_MODULE (documentación de Node.js). Es un error distinto, pero aparece en el mismo lugar. En esa situación, cambia a import().

¿Cómo evitar que vuelva?#

• Trata el lockfile como parte del código: haz commit de package-lock.json y usa npm ci para instalar.
• Mantén los paquetes de runtime en dependencies.
• Nombra los archivos en minúsculas e impórtalos exactamente con la misma escritura.
• En ES modules, escribe siempre la extensión.
• Fija los paquetes de Python en requirements.txt e instala con el mismo intérprete que ejecuta la app.
• Prueba en local la forma desplegada: borra node_modules, ejecuta npm ci y arranca la app. Si falla ahí, fallará en el servidor.

Para otros fallos de deploy relacionados, mira cómo leer errores de build, cómo leer los logs de tu aplicación y cómo hospedar una app Node.js.

Cómo hacerlo en Square Cloud#

En Square Cloud haces el deploy subiendo un ZIP, con la CLI, con un push a GitHub o con la extensión de VS Code. Elijas lo que elijas, la primera comprobación es la misma: abre los logs en tiempo real, copia el nombre del módulo del error y compáralo con los archivos que realmente subiste. Al iniciar, la plataforma ejecuta npm install cuando no existe node_modules, con NODE_ENV=production: un paquete que solo está en devDependencies no se instala y provoca este error.

El gestor de archivos en el navegador te muestra los archivos de tu aplicación, así que puedes confirmar que la ruta del error existe y que sus mayúsculas coinciden. El editor guarda directamente en la aplicación, sin redeploy.

Si el error nombra tu archivo de entrada, comprueba que la configuración del archivo principal apunta a un archivo que existe. Esa configuración está en squarecloud.app, que es opcional: el panel puede generarlo en el deploy (runtime, memoria, archivo principal) o puedes escribirlo en la raíz del proyecto. No hay paso de build, así que un punto de entrada en dist exige subir la carpeta ya compilada o poner el build en el comando de inicio.

Cuando tengas el arreglo en local, envíalo con el comando commit de la CLI o con un push a GitHub mediante la GitHub Action oficial, que puede ejecutar commit --restart en cada push. El flujo completo está en la página de la CLI.