# Troubleshooting Medusa

Most Medusa problems on TurboStack have one root cause: the Node process is not running and listening on the port Nginx proxies to. Because the platform only provides the reverse proxy, Transport Layer Security (TLS), PostgreSQL, and the Node runtime, the application process is yours to keep healthy. This page shows where to look and how to fix the common cases.

## Where to find the logs

Medusa runs as your own Node process, so its application output goes wherever your process manager writes it. The platform components have fixed locations:

| Component | Where |
| --- | --- |
| Nginx access log (per vhost) | `/var/log/nginx/<user>_<app_name>.log` |
| Nginx error log | `/var/log/nginx/error.log` (proxy/502 errors land here) |
| Medusa application log | wherever your process manager directs stdout/stderr (for example the systemd journal via `journalctl -u <service>`, or PM2 logs) |
| PostgreSQL | the PostgreSQL service log on the host |
| Host metrics & service status | the host's [Health](../../platform/hosts/health.md) tab |
| Recent deploys | [History](../../platform/hosts/revisions.md) |

> [!TIP]
> A 502 is almost always logged in `/var/log/nginx/error.log` with a "connect() failed" or "upstream prematurely closed" message naming the upstream port. That tells you immediately whether Nginx reached your Node process.

## Common issues

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| **502 Bad Gateway** | The Node process is not running, or not listening on `proxy_upstream_port` | Start the process; confirm it listens on the configured port (`ss -ltnp | grep <port>`); ensure `proxy_upstream_port` matches the port the app binds to |
| **502 only after a deploy / under load** | Process crashed on startup or is crash-looping | Read the application log for the stack trace; verify the build succeeded and env vars are set; run the process under a supervisor so it restarts |
| **App starts then exits immediately** | Missing or wrong environment variables (database URL, JWT/cookie secrets, Redis URL) | Set the required env vars for the process; restart after correcting them |
| **Database errors / "connection refused"** | Wrong PostgreSQL connection string, or pool exhausted | Verify the database URL, credentials, and that PostgreSQL is running; reduce pool size if connections are exhausted across server and worker |
| **"relation does not exist" / schema errors** | Migrations not run for the deployed version | Run `medusa db:migrate` before starting the new code |
| **Admin dashboard blank or 404** | The app was not built, or the wrong vhost/port serves the admin | Run `medusa build`; confirm the storefront and backend/admin use the correct separate ports and vhosts |
| **Events/jobs not firing** | Redis not configured, or no worker process running | Point Medusa at Redis and run a worker-mode process for background jobs |

## A troubleshooting workflow

1. **Check [Health](../../platform/hosts/health.md)** - confirm the host has CPU, memory, and disk headroom, and that core services are up.
2. **Read the relevant log** - for a 502, start with `/var/log/nginx/error.log`. For app crashes, read the Medusa application log (your process manager's output). For database errors, check the PostgreSQL log.
3. **Check the last deploy in [History](../../platform/hosts/revisions.md)** - if a recent change broke the app, revert or re-publish the previous configuration ([Publishing](../../platform/hosts/publishing.md)).
4. **Verify services are running** - confirm the Node process is alive and listening on `proxy_upstream_port`, and that PostgreSQL (and Redis, if used) are running. Restart whatever is down via your process manager or the host's [Services](../../platform/hosts/services.md) tab.

## Getting help

If you are stuck after working through the steps above, see the general [Troubleshooting](../../platform/troubleshooting.md) guide and reach out via [Support](../../platform/support.md). Include the failing domain, the Nginx and application log excerpts, and what changed in the last deploy.

## Related

- [Deploy Medusa](deploy.md)
- [Medusa best practices](best-practices.md)
- [Health](../../platform/hosts/health.md)
- [Support](../../platform/support.md)