Troubleshooting Medusa

Diagnose Medusa on TurboStack - fix Nginx 502 errors, PostgreSQL connection and migration problems, build and process-manager issues, and find the right logs.

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 tab
Recent deploys History

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 - 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 - if a recent change broke the app, revert or re-publish the previous configuration (Publishing).
  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 tab.

Getting help

If you are stuck after working through the steps above, see the general Troubleshooting guide and reach out via Support. Include the failing domain, the Nginx and application log excerpts, and what changed in the last deploy.

© 2026 Hosted Power — TurboStack