---
title: "What to do when an app works locally but not in production"
description: "Diagnose build, runtime, port, environment, persistence, and routing differences when a local app fails after deployment."
canonical_url: "https://ample.computer/guides/works-locally-not-production"
last_updated: "2026-07-30"
author: "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.

   ```sh
   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.

   ```sh
   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

- 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

## 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

- [How to get an app from localhost onto the internet](https://ample.computer/guides/localhost-to-internet)
- [How to add environment variables during deployment](https://ample.computer/guides/environment-variables-deployment)
- [How to redeploy after changing an AI-built app](https://ample.computer/guides/redeploy-ai-built-app)

## Machine-readable resources

- [llms.txt](https://ample.computer/llms.txt) | [AGENTS.md](https://ample.computer/AGENTS.md) | [sitemap.md](https://ample.computer/sitemap.md) | [OpenAPI](https://ample.computer/openapi.json)