Healthcheck Behavior and Status Meanings

Published · Last updated: May 2026 · 3 min read

Who this is for

Users who want to understand how CloudAIPilot determines whether an app is healthy, and what the different app statuses mean.

What Is a Healthcheck?

A healthcheck is an HTTP endpoint on your application that CloudAIPilot calls to verify the app is ready to receive traffic. For example, /health or /api/ping.

When the healthcheck returns HTTP 200, the app is considered healthy. Any other response or a connection failure is considered unhealthy.

How to Configure a Healthcheck

Set the Health path field when creating or updating an app:

Example: /health
Example: /api/status
Example: / (the homepage — less ideal but works)

The path is called on http://localhost: from the server.

App Status Values

Status	Meaning
`pending`	App was just created — deploy triggered or waiting to start
`running`	Container is running (healthcheck passing, or healthcheck not configured)
`stopped`	Container is not running — either manually stopped or `restartPolicy: no` after a graceful exit
`failed`	Container exited with a non-zero exit code — or healthcheck failed persistently
`deleting`	App is being cleaned up after a delete request

How Status Is Determined

pending → running: CloudAIPilot runs docker start or docker run and polls the container status.
running → failed: Container exits with non-zero exit code, or repeated healthcheck failures.
running → stopped: Container exits cleanly (exit code 0) or is manually stopped.
deleting: Triggered by a delete operation — intermediate state before the row is soft-deleted.

How Healthcheck Is Used for Zero-Downtime Deploys

When zeroDowntimeEnabled is true and the app has a custom domain:

CloudAIPilot builds and starts the new container on a temporary port.
It calls the healthcheck endpoint on the new container.
Only when the healthcheck returns 200 does CloudAIPilot swap the Nginx proxy to the new container.
The old container is stopped only after the swap is confirmed.

If the healthcheck never returns 200 within the timeout period, the deploy is considered failed and the old container keeps serving traffic.

What If I Don't Set a Health Path?

CloudAIPilot uses Docker container status (running/exited) as a proxy for health. The app is considered running as long as the Docker container process is alive. Zero-downtime deploys require a health path — without one, traffic is switched immediately upon container start.

What Success Looks Like

App shows running status. If a healthcheck is configured and zero-downtime deploys are enabled, new deploys complete without any 502 errors for end users.

Common Issues and Fixes

Issue	Likely cause	Fix
App shows "running" but healthcheck fails externally	Health path only checked internally	Verify the app is listening on the correct container port.
Zero-downtime deploy times out	Healthcheck endpoint returns non-200 during startup	The app needs time to warm up. Consider adding a startup delay or adjusting the health endpoint to return 200 earlier.
App stuck in "pending"	Docker pull taking long, or SSH failure	Check Activity Center for deploy step details.