BahriyaBAHRIYAby Mamluk

Container Won't Start or Keeps Crash-Looping

Your container deploys but never reaches a healthy running state — it starts, exits, and starts again in a loop. This is almost always the application failing on startup, and the logs will tell you why.

Updated 3 Aug 20262 min read

Your container deploys but never reaches a healthy running state — it starts, exits, and starts again in a loop. This is almost always the application failing on startup, and the logs will tell you why.

Symptoms

  • The container starts and then restarts repeatedly, without ever settling into a running state.
  • The status flips between starting and restarting, or the container never becomes healthy.
  • Application logs show a crash, stack trace, or exit shortly after boot.

Likely causes

  • The port is wrong. Your application listens on a different port than the one configured (defaults to 8080). Bahriya sends traffic and health checks to the configured port only.
  • The application binds to localhost instead of 0.0.0.0. A server bound to 127.0.0.1 inside the container is unreachable from outside it, so health checks never pass.
  • A required environment variable or secret is missing. The application throws on boot when a config value or credential it expects is not present.
  • The image or entrypoint is broken. A bad start command, a missing binary, or an image built for the wrong architecture causes an immediate exit.
  • The application crashes on startup — a failed database connection, a migration error, or an unhandled exception during initialisation.
  • Startup is slower than the bootstrap time allows, so the container is declared failed before it finishes initialising.

How to fix

  1. Read the application logs. Open the container detail page and check the logs around the time of each restart. A stack trace or an error message usually points straight at the cause.
  2. Confirm the port. Make sure the configured container port matches the port your application actually listens on, and that the app binds to 0.0.0.0 (all interfaces), not localhost.
  3. Check environment variables and secrets. Verify every value your application needs is attached, and that any secrets are deployed to the same regions as the container. See Environment Variables.
  4. Verify the health check path exists and returns a 2xx response. A common mistake is pointing the health check at a route that returns 404. See Health Checks.
  5. Run the image locally to reproduce the crash: docker run -p 8080:8080 <your-image>. If it fails on your machine, it will fail on the platform. Pass the same environment variables the container expects.
  6. Increase the bootstrap time if the application is slow to start — for example, when it loads large datasets or runs migrations on boot.
Tip

Reproducing the container locally with docker run and the real environment variables is the single fastest way to find a startup crash. If it starts cleanly locally but not on the platform, the difference is almost always a missing env var, a missing secret, or the port.