# podman healthcheck: Wait For a Service in CI

> podman healthcheck and --health-cmd let CI wait until a container is healthy. Reference for the health flags, run, and the status and timing errors in CI.

Source: https://latchkey.dev/learn/command-reference/podman-healthcheck  
Updated: 2026-06-30

podman healthcheck runs a container health probe, and the --health-cmd flags define one so CI can wait until a service is ready.

Tests that race a slow-starting service flake. A health check plus a wait loop on the health status makes the pipeline deterministic.

## What it does

A health check is a command Podman runs inside a container on an interval; its exit status sets the container health to starting, healthy, or unhealthy. podman healthcheck run triggers it on demand, and podman inspect reads the resulting status.

## Common usage

```Terminal
podman run -d --name db \
  --health-cmd 'pg_isready -U postgres' \
  --health-interval 5s --health-retries 5 --health-start-period 10s \
  docker.io/library/postgres:16
# wait until healthy
until [ "$(podman inspect -f '{{.State.Health.Status}}' db)" = healthy ]; do sleep 2; done
podman healthcheck run db
```

## Options

| Flag/Command | What it does |
| --- | --- |
| --health-cmd <cmd> | Command that probes container health |
| --health-interval <dur> | Time between checks |
| --health-retries <n> | Failures before marking unhealthy |
| --health-start-period <dur> | Grace period before failures count |
| healthcheck run <ctr> | Run the check once on demand |
| {{.State.Health.Status}} | Inspect field with the current status |

## In CI

Define a health check on service containers and poll {{.State.Health.Status}} in a bounded until loop before running tests, so a slow database does not cause flaky failures. Cap the loop with a timeout so a never-healthy container fails the job instead of hanging.

## Common errors in CI

"Error: container ... has no defined healthcheck" from podman healthcheck run means the image and run command set no --health-cmd; add one. A status stuck at "starting" means the start period has not elapsed or the probe never succeeds; check the command with podman exec. An unbounded wait loop hangs the job when the container is "unhealthy"; add a max iteration count.

## FAQ

### podman healthcheck: Wait For a Service in CI?

Tests that race a slow-starting service flake. A health check plus a wait loop on the health status makes the pipeline deterministic.

### What it does?

A health check is a command Podman runs inside a container on an interval; its exit status sets the container health to starting, healthy, or unhealthy. podman healthcheck run triggers it on demand, and podman inspect reads the resulting status.

### In CI?

Define a health check on service containers and poll {{.State.Health.Status}} in a bounded until loop before running tests, so a slow database does not cause flaky failures. Cap the loop with a timeout so a never-healthy container fails the job instead of hanging.

### Common errors in CI?

"Error: container ... has no defined healthcheck" from podman healthcheck run means the image and run command set no --health-cmd; add one. A status stuck at "starting" means the start period has not elapsed or the probe never succeeds; check the command with podman exec.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt