What to do when an app works locally but not in production | Ample
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
Before you start
This guide is for builders whose local development workflow succeeds but whose deployed release fails to build, start, or behave correctly.
STEP BY STEP
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.
FIT CHECK
What this supports
Good fit
- Separate build and runtime log views
- Health-check failure details
- Runtime mismatch guards
- Plan evidence for common packaging and data risks
Know the limits
- Ample cannot repair an application bug without a source change
- Local-only services are not automatically available in production
- Release filesystems are not a substitute for durable storage
TROUBLESHOOTING
Common failure modes
The process listens on localhost
Bind to 0.0.0.0 and read the PORT environment variable.
The app connects to a local database or API
Use a managed resource, deployed service link, or production environment variable.
The server image lacks the runtime
Deploy to a new runtime-matched server instead of reusing an incompatible one.
Data disappears after restart
Move runtime-written files to an attached volume or managed database.
Related guides
Localhost to live How to get an app from localhost onto the internet Environment variables How to add environment variables during deployment Safe redeployment How to redeploy after changing an AI-built app