My application won't start: Verifying the start script

Often, the reason an application fails to get off the ground on Square Cloud is not a complex logic error, but rather the initial "trigger". If the platform does not know exactly how to fire up your code, it will terminate the process before it even loads your first line of functions.

1. Main File vs. Custom Command

There are two ways to tell Square Cloud how your application should start:

• Main File (Main): You point directly to the file (e.g., index.js or main.py). The platform will attempt to execute it using the default interpreter.
• Custom Command (Start Command): You define a complete command line. This is the recommended approach for applications that use frameworks or production servers, as it offers greater control.

2. The "Path" Issue and Uninstalled Libraries

A classic error is trying to execute a command that is not in the system's "Path" (the environment path for direct execution). If you define a command that calls a library that hasn't been installed or that the system cannot locate globally, the application will fail immediately.

Tip: Always prefer to invoke libraries through their respective package managers (npm, python -m, etc.), as they know exactly where to look for installed files within your application's environment.

3. Common Case: Next.js (Node.js)

For Next.js to function correctly on Square Cloud, it needs to be treated as a full production application:

• Dependency Configuration: Next.js must be listed under dependencies in your package.json, and not under devDependencies. Otherwise, the platform will not find it during execution.
• The Start Command: Avoid trying to run the binary directly. Use the NPM script in your custom start command instead:

    npm run start

This ensures that the package manager locates Next inside the node_modules folder and executes the process safely (keeping in mind that the start script in your package.json should contain next start -p 80).

4. Common Case: Python Webservers (Gunicorn)

In Python, it is common for the gunicorn command not to be found if typed alone in the start command field, because it might not be in the system's direct path. The most robust way to guarantee initialization is by calling the module through the Python interpreter.

• Recommended Command:

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

• Why use -m? The -m flag tells Python to look for the module within the libraries installed in the environment. This resolves most "command not found" issues.

5. Diagnostic Checklist

If your application is not starting, verify the following points:

1. Installation: Is the library you are trying to call (like gunicorn or next) listed in your package.json or requirements.txt?
2. Syntax: In your custom command, did you include all the required arguments, especially port 80 for webservers?
3. Location: If your main file is inside a folder (e.g., src/main.py), does your start command accurately reflect this path?
4. Environment: Does the command you configured work locally if you delete your virtual environment folder (venv or node_modules) and reinstall everything from scratch?

Updated on: 05/22/2026