Skip to main content

T1. App works locally but not online

What this page helps you do​

Work through the most common reasons an app runs on your machine but fails after deploy.

Why it matters​

This is one of the most common launch problems. It usually means something about the production environment is different from local in a way the app depends on.

You should already have​

  • a working local app
  • a failed or partially working deployment

Skip this page if​

  • the app does not even run locally yet

Then go back to F4. Run your app locally.

What to do​

Check the usual gaps first:

  1. Environment settings are missing or named differently.
  2. Build commands differ between local and production.
  3. The app starts locally with hidden dependencies the host does not have.
  4. The database or external service URL is wrong.
  5. The app is running, but the domain points to the wrong place.
  6. The app crashes on startup and only the logs know why.

Simple debugging order:

  1. Check the deploy logs.
  2. Check the startup command.
  3. Check environment settings.
  4. Check database or service connections.
  5. Check the domain and HTTPS only after the app itself is healthy.

Assume the problem is something boring before you assume it is something advanced.

Most of the time it is:

  • a missing setting
  • a wrong command
  • a wrong target URL
  • a hidden local dependency

Common mistakes​

  • debugging DNS before checking whether the app booted
  • changing five things at once
  • trusting a green deploy badge without opening the logs

Next step​

If the app itself is healthy, go to T2. Domain not working or D3. Point your domain to your app.

Advanced notes​

If the app only fails under real production traffic, check for file paths, permissions, timeouts, and rate limits that local development never exercised.