## 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. 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. 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. 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. 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. 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**](/content/guides/localhost-to-internet/index.html) [Environment variables **How to add environment variables during deployment**](/content/guides/environment-variables-deployment/index.html) [Safe redeployment **How to redeploy after changing an AI-built app**](/content/guides/redeploy-ai-built-app/index.html)