What to do when an app works locally but not in production · Ample Computer

What to do when an app works locally but not in production

Diagnose build, runtime, port, environment, persistence, and routing differences when a local app fails after deployment.

the short version

When an app works locally but not in production, split the problem into build and runtime stages. Read the matching Ample logs, then check the production start command, PORT binding, environment variables, deployed service URLs, runtime compatibility, and durable storage. Fix the cause before creating another deployment.

Who this is for

This guide is for builders whose local development workflow succeeds but whose deployed release fails to build, start, or behave correctly.

How to do it

  1. Classify the failure. A build failure happens before the release boots. A runtime failure happens after packaging, during startup or health checking. A browser-only failure happens after the route is live.

  2. Read build logs. Look for missing files, dependency errors, type failures, workspace resolution, or required build-time environment variables.

    $ ample logs <deployment_id> --kind build
    
  3. Read runtime logs. Look for a crashed start command, missing runtime values, database connection errors, or a process that never binds to the assigned port.

    $ ample logs <deployment_id> --kind runtime
    
  4. Compare production assumptions. Replace localhost dependencies, use 0.0.0.0:$PORT, put durable data on a volume or database, and make sure the server template contains the required language.

  5. Fix and deploy once. Change the source or configuration, then run the deploy again. Do not blind-retry an unchanged failure.

What this supports

Know the limits

Common failure modes