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

# 502 error resolution guide

> Diagnose and resolve common 502 errors that may prevent your Upsun app from starting or running correctly.

<Note>
  If you'd like to learn more about troubleshooting your application, visit the [troubleshoot development](/docs/troubleshooting/general/) page.
</Note>

When deploying an application on Upsun, it's essential that your app's startup process is correctly configured to ensure smooth operation.

This guide provides a step-by-step approach to troubleshoot 500 errors related to your app not starting, crashing, or failing to connect to required services.

### Step 1: Check logs for troubleshooting insights

You can start your troubleshooting process by looking into some of the logs listed below:

* **Deploy logs**

These show what happened during build and deploy. You can view them by using the following command in terminal:

```bash theme={null}
upsun log deploy
```

<Note>
  Note that the Deploy logs will only populate if the deploy hook runs as part of your deployment.
</Note>

Deploy logs are especially helpful if you're running migrations or provisioning services - issues with database credentials, missing tables, or failed connections often appear here.

* **App logs**

The app log can be particularly useful for debugging your start command. To gain insight into what might be going wrong with your app in particular, use the following command in terminal:

```bash theme={null}
upsun log app
```

This log often reveals stack traces, syntax errors, or missing dependencies that may be preventing the app from starting.

* **All available logs**

To explore what other logs are available to help with troubleshooting, use the following command in terminal:

```bash theme={null}
upsun log
```

### Step 2: Ensure your app's web start command is running

If you've configured a `web.command.start` in your `./upsun/config.yaml`, make sure:

* It launches your app process reliably (e.g. `npm start`, `gunicorn` etc.)

* It doesn't exit immediately or crash

* **It binds to the port provided by the `PORT` [environment variable](/docs/development/variables/use-variables#use-provided-variables)**

To confirm which port your app should bind to, run:

```bash theme={null}
upsun ssh 'echo $PORT'
```

If your app is hardcoded to listen on a specific port like 3000 or 8000, it won't work --- it needs to use the dynamic port assigned by Upsun. It should also be noted that **this command can only be run in a local session**, not in the app container (in a terminal session).

<Note>
  Please note that if the [\$PORT](/docs/development/variables/use-variables#use-provided-variables) is empty, you will need to check if `web.upstream.socket_family`is set to `tcp`.

  You may see a 502 error if your application isn’t [listening at the same place](/docs/configure-apps/image-properties/web#where-to-listen) that the runtime is sending requests.
</Note>

### Step 3: Review recent activity

Use the Console or [CLI](/cli/index) to inspect recent deploys and other operations:

* In the **Console**, go to your environment view and **select an activity to review**.

* Or, in the CLI:

```bash theme={null}
upsun activity:log     # View the most recent log
upsun activity:list    # See a list of recent activities`
```

Look for failed steps, timeouts, or warnings.

### Step 4: SSH into the running container

If the logs aren't telling the full story, you can directly inspect your running environment with this command:

```bash theme={null}
upsun ssh
```

This is especially useful for:

* Viewing log files created by your app that aren't exposed via the `Upsun log`
* Checking if writable directories are correctly mounted
* Testing internal service connections and inspecting the filesystem

<Info>
  <h4>Bonus step</h4>
  You can also manually run your `start` command to debug why your app might be failing. This is because some output about issues in standard output (`stdout`) don't always appear in the logs.
</Info>

To confirm mount points are correctly defined and available, run:

```bash theme={null}
upsun mount:list
```

This lists all writable mounts available in your environment and their paths.

### Step 5: Verify service connectivity

If your app uses [databases or other services](/docs/add-services/index), make sure it can reach them from within the container with the command below:

```bash theme={null}
ping database.internal
psql $DATABASE_URL
```

Make sure the services are defined in `.upsun/config.yaml`,`services`, the top level key and linked correctly in your app configuration.

## Further resources

* [Troubleshooting](/docs/troubleshooting/general/)
* [Use variables](/docs/development/variables/use-variables#use-provided-variables)
* [Add services](/docs/add-services/index)
* [Using the CLI tool](/cli/index)