# Troubleshoot a Docker app

> Diagnose build, startup, health, routing, storage, and resource failures in the correct order.

## Build or pull fails

Open **Build Logs** and find the first failing command. Verify the repository URL and branch, Dockerfile or Compose paths, base image availability, image architecture, and required build values. For an image source, confirm the tag exists and can be pulled without credentials not supplied to AppLaunch.

## App starts and then stops

Open **Logs**. Confirm the main process stays in the foreground, the startup command is valid, required environment variables exist, and dependencies are reachable. A container exits normally when its main process finishes.

## Domain returns 502 or unavailable

1. Confirm the app status is **Running**.
2. Confirm the process listens on `0.0.0.0`, not only localhost.
3. Match **Configuration → Ports** target port to the application's actual internal port.
4. Test the application logs while making one request.
5. For DNS verification, use **DNS only** and remove conflicting records.

## Direct port does not connect

Use the displayed public hostname and allocated port, not the internal target port. Confirm TCP or UDP matches the client, the node is online, and the application listens on that protocol.

## Files disappear after redeploy

Changes in **Container Filesystem** are ephemeral. Move durable data to a mounted persistent volume and change application code in the source or image. See [Manage Docker files and volumes](/docker/files-and-volumes/).

## App is slow or killed

Open **Usage** and compare CPU, RAM, storage, bandwidth, app, container, and public-port use with plan limits. Reduce consumption or change the plan before repeatedly restarting a process that is consistently over its limits.

## Get help

Create a [support ticket](https://applaunch.org/dashboard/support) with the service and app names, source type, exact action, approximate UTC time, status, and the relevant build or runtime log excerpt. Remove environment secrets, tokens, and customer data.