Mi aplicación no inicia: Verificando el script de inicio

Muchas veces, el motivo por el cual una aplicación no arranca en Square Cloud no se debe a un error complejo de lógica, sino al "disparador" inicial. Si la plataforma no sabe exactamente cómo dar inicio a tu código, finalizará el proceso antes incluso de cargar tu primera línea de función.

1. Archivo principal vs. Comando personalizado

Existen dos formas de decirle a Square Cloud cómo debe iniciar tu aplicación:

• Archivo principal (Main): Apuntas directamente al archivo (ej: index.js o main.py). La plataforma intentará ejecutarlo utilizando el intérprete por defecto.
• Comando personalizado (Start Command): Defines una línea de comandos completa. Esta es la forma recomendada para aplicaciones que utilizan frameworks o servidores de producción, ya que ofrece un mayor control.

2. El problema del "Path" y bibliotecas no instaladas

Un error clásico es intentar ejecutar un comando que no está en el "Path" (ruta de ejecución directa) del sistema. Si defines un comando que llama a una biblioteca que no ha sido instalada o que el sistema no localiza globalmente, la aplicación fallará inmediatamente.

Consejo: Prefiere siempre invocar bibliotecas a través de sus respectivos gestores de paquetes (npm, python -m, etc.), ya que estos saben exactamente dónde buscar los archivos instalados dentro del entorno de tu aplicación.

3. Caso común: Next.js (Node.js)

Para que Next.js funcione correctamente en Square Cloud, debe ser tratado como una aplicación de producción completa:

• Configuración de dependencias: Next.js debe estar listado en dependencies dentro de tu package.json, y no en devDependencies. De lo contrario, la plataforma no lo encontrará durante la ejecución.
• El comando de inicio: Evita intentar ejecutar el binario directamente. Utiliza el script de NPM en tu comando de inicio personalizado:

    npm run start

Esto garantiza que el gestor de paquetes localice Next dentro della carpeta node_modules y ejecute el proceso de forma segura (recordando que el script start en tu package.json debe contener next start -p 80).

4. Caso común: Servidores web Python (Gunicorn)

En Python, es común que el comando gunicorn no sea encontrado si se escribe solo en el campo de comando de inicio, ya que puede no estar en el path directo del sistema. La forma más robusta de garantizar la inicialización es utilizando el módulo a través del intérprete de Python.

• Comando recomendado:

    python -m gunicorn --bind 0.0.0.0:80 app:app

• ¿Por qué el -m?: El parámetro -m le indica a Python que busque el módulo dentro de las bibliotecas instaladas en el entorno. Esto resuelve la mayoría de los problemas de "command not found".

5. Checklist de diagnóstico

Si tu aplicación no está iniciando, verifica los siguientes puntos:

1. Instalación: ¿La biblioteca que estás intentando llamar (como gunicorn o next) está en tu package.json o requirements.txt?
2. Sintaxis: En el comando personalizado, ¿incluiste todos los argumentos necesarios, especialmente el puerto 80 para servidores web?
3. Ubicación: Si tu archivo principal está dentro de una carpeta (ej: src/main.py), ¿tu comando de inicio refleja esa ruta correctamente?
4. Entorno: ¿El comando que configuraste funciona localmente si eliminas tu carpeta de entorno virtual (venv o node_modules) y reinstalas todo desde cero?

Actualizado el: 12/06/2026