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

# App Won't Start: Deploy, Site and Boot Errors

> Fix a Square Cloud app that won't deploy, start or load: upload errors, timeouts on port 80, EADDRINUSE, Cannot find module, INVALID_DEPENDENCY and UTC times.

If your application is rejected at upload, crashes at boot or never answers, the error code or the console log almost always names the exact problem. Match it below.

## Upload and deploy errors

These codes come back from the dashboard, the CLI or the API when Square Cloud rejects an upload. Nothing is deployed, so fix the cause and upload again.

| Code | What it means | How to fix |
| - | - | - |
| `FILE_TOO_LARGE` | The zip is larger than 100 MB. | Leave out `node_modules`, build output and large media. Store big files in [Blob Storage](/en/services/blob) instead. |
| `INSUFFICIENT_MEMORY` | `MEMORY` is below the minimum for the project type, or higher than the RAM your plan still has free. | Check the [minimum RAM](/en/platform/limitations-and-restrictions#minimum-resource-requirements). To free RAM, delete an application you don't use, lower another one's RAM, or upgrade your plan. |
| `MISSING_CONFIG` | There is no `squarecloud.app` or `squarecloud.config` at the top level of the zip, or it is empty. | Zip the contents of your project folder, not the folder itself. |
| `MISSING_MEMORY`, `MISSING_DISPLAY_NAME`, `MISSING_VERSION` | A required field is missing from the configuration file. | Add it. See the [configuration file](/en/getting-started/config-file#configuration-parameters). |
| `MISSING_MAIN`, `INVALID_MAIN` | `MAIN` is missing, points to a file that isn't in the zip, is empty or breaks the naming rules. | Check the [`MAIN` rules](/en/getting-started/config-file#main). |
| `INVALID_VERSION` | `VERSION` isn't `recommended` or `latest`. | Use one of the two values. |
| `INVALID_RUNTIME`, `INVALID_START` | `RUNTIME` has an unknown value, or `START` is longer than 256 characters. | See [`RUNTIME`](/en/getting-started/config-file#runtime) and [`START`](/en/getting-started/config-file#start). |
| `INVALID_DISPLAY_NAME`, `INVALID_DESCRIPTION` | The name has characters outside letters, digits, spaces, `-` and `_`, or is longer than 32 characters; or the description is longer than 280. | See [`DISPLAY_NAME`](/en/getting-started/config-file#display_name). |
| `INVALID_SUBDOMAIN` | The subdomain is invalid, reserved or already taken. | Pick another name. See [`SUBDOMAIN`](/en/getting-started/config-file#subdomain). |
| `INVALID_DEPENDENCY` | The dependency file is missing or empty. | See [INVALID\_DEPENDENCY](#invalid_dependency) below. |
| `FAILED_EXTRACT` | The file isn't a valid zip archive. | Create the zip again with your system's compress option or `zip -r`. |
| `KEEP_CALM` | You repeated an action too quickly. | See [KEEP\_CALM](#keep_calm) below. |

### INVALID\_DEPENDENCY

**What it means:** the upload has no dependency file for its language, or the file is empty. Square Cloud checks that this file exists at the root of the zip before it installs anything.

**How to fix:** put the dependency file at the root of the zip, next to `squarecloud.app`, and make sure it isn't empty: `package.json` (Node.js, Bun, Deno), `requirements.txt` or `pyproject.toml` (Python), `Cargo.toml` (Rust), `Gemfile` (Ruby), `go.mod` or `go.work` (Go) or `mix.exs` (Elixir). Then upload again. A misspelled package or version shows up later, as an install error in the logs.

### KEEP\_CALM

**What it means:** you, or an automation, repeated an action too quickly, such as a restart, an upload or a snapshot.

**How to fix:** wait a moment and try again. The rejected action simply didn't run: `KEEP_CALM` never stops or affects a running application. If a snapshot fails with `DAILY_SNAPSHOTS_LIMIT_REACHED` instead, your plan's daily snapshot allowance is used up until the next day.

## Website doesn't load

**What it means:** the application is deployed, but opening its address shows one of these pages instead of your site:

* **"The website took too long to respond"**: Square Cloud found your application but got no answer from it.
* **"This site couldn't be found"**: no website is published at that address.

**How to fix a timeout:**

1. Make your server listen on port `80` and host `0.0.0.0`. A server bound to `localhost`, `127.0.0.1` or any other port (3000, 5173, 8080...) can't be reached. The runtime sets the `PORT` and `HOST` environment variables to these values, so read them:

   <CodeGroup>
     ```javascript Node.js (Express) theme={"system"}
     app.listen(process.env.PORT || 3000, process.env.HOST || "0.0.0.0", () => {
       console.log("Server running");
     });
     ```

     ```python Python (Flask) theme={"system"}
     import os

     app.run(host=os.environ.get("HOST", "0.0.0.0"), port=int(os.environ.get("PORT", 3000)))
     ```
   </CodeGroup>
2. Open the logs: if the application crashed or is still installing dependencies or building, the site can't answer yet. Fix the error shown there, or wait for the build to finish.
3. Check that `MEMORY` gives the build enough room: a framework build that runs out of RAM stops the application with [`LACK_OF_RAM`](/en/platform/limitations-and-restrictions#lack_of_ram).

**How to fix "This site couldn't be found":**

1. Check the address: it's `https://<SUBDOMAIN>.squareweb.app`, with the subdomain from your configuration file.
2. If you just deployed, wait up to a minute for the address to be published.
3. An application deployed without `SUBDOMAIN` isn't a website and can't become one: upload it again as a new application with [`SUBDOMAIN`](/en/getting-started/config-file#subdomain) set.
4. On a custom domain, the DNS may still be propagating. See [why your domain hasn't propagated yet](https://help.squarecloud.app/en-us/article/why-hasnt-my-domain-propagated-yet-dns-f5jzoy/).

## EADDRINUSE (port already in use)

**What it means:** the app tries to bind the same network port twice.

**Why it happens:** two servers are started in the code, or a `listen(...)` call gets created again inside an event handler (for example, on every request or every reconnect) instead of once at startup.

**How to fix:**

1. Start **one** web server, **once**, listening on port `80` and host `0.0.0.0`.
2. Search your code for more than one `.listen()` (Node.js) or `run()` (Python/Flask/Django) call and remove the duplicate.
3. Make sure the listen call sits at the top level of your startup file, not inside a callback that can fire more than once.

## "Cannot find module" (Node.js) and ModuleNotFoundError (Python)

**What it means:** a package your code imports isn't installed.

**Why it happens:**

* The library isn't listed in `package.json`'s `dependencies` (Node.js) or in `requirements.txt`/`pyproject.toml` (Python), so it never gets installed on the platform, even if it works on your machine.
* In Node.js, the package is only in `devDependencies`. Applications run with `NODE_ENV=production`, so `npm install` skips development dependencies.

**How to fix:**

1. Add the missing package to `dependencies` (or your Python dependency file) with a valid version.
2. Confirm the dependency file itself is included in the zip you uploaded.
3. Restart the application. For Node.js, dependencies are only installed when `node_modules` doesn't exist: delete `node_modules` (and `package-lock.json`, if you uploaded one) in the dashboard's file manager, then restart for a clean reinstall.

## better-sqlite3 / native bindings errors

**What it means:** an error like `Could not locate the bindings file` when your app uses `better-sqlite3` (directly, or through `quick.db`).

**Why it happens:** the installed `better-sqlite3` version predates the platform's current Node.js LTS, so its prebuilt native binding doesn't match the runtime.

**How to fix:**

1. Update `better-sqlite3` to `12.5.0` or later (if you use `quick.db`, update it to `9.1.7` or later).
2. Delete `node_modules` **and** `package-lock.json`.
3. Restart the application for a clean reinstall that rebuilds the native bindings against the current runtime.

## Stopped by a resource limit

If the logs end with `[SQUARE-SHIELD] LACK_OF_RAM`, `LACK_OF_CPU` or `ABUSE_REQUESTS`, or starting the application fails with `CONTAINER_TEMPORARILY_SUSPENDED`, Square Cloud stopped it for going over its resources. The [status table](/en/platform/limitations-and-restrictions#limit-exceeded-statuses) explains each one and how to fix it.

## Times are off by a few hours

Applications run in UTC. A job scheduled for 09:00 runs at 09:00 UTC, and the times your code prints to the logs are in UTC. Convert times in your code, or see [how to change your application's time zone](https://help.squarecloud.app/en-us/article/how-to-change-your-applications-timezone-y525ae/) in the help center.

## Related guides

* [Configuration file](/en/getting-started/config-file): every field and the error it raises.
* [Environment variables](/en/platform/environment-variables): set secrets, then restart to apply them.
* [Discord bot errors](/en/platform/troubleshooting/discord-bot-errors) and [database connection errors](/en/platform/troubleshooting/database-connection-errors).

<Tip>Still stuck after checking the logs against the errors above? Our support team can look at the specific crash with you.</Tip>

## Contact us

If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot.


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