GitHub Actions service container options health-cmd invalid

Service containers can declare a health check via the options field using Docker run flags like --health-cmd. A malformed health-cmd (bad quoting, wrong command) means the container never reports healthy, and dependent steps wait or fail.

What this error means

A service container never reaches a healthy state and the job stalls or fails waiting on it.

services:
  db:
    image: postgres:16
    options: >-
      --health-cmd pg_isready   # missing quoting/db user -> health check never passes

Common causes

health-cmd not properly quoted

A multi-word health command needs correct quoting in the options string.

Health command itself fails

If the command exits non-zero (wrong user/db), the container is reported unhealthy forever.

How to fix it

Quote and complete the health command

1. Wrap the command and add health interval/timeout/retries.
2. Ensure the command actually succeeds for the service config.

services:
  db:
    image: postgres:16
    env:
      POSTGRES_PASSWORD: pass
    options: >-
      --health-cmd "pg_isready -U postgres"
      --health-interval 10s
      --health-timeout 5s
      --health-retries 5

Test the health command locally

1. Run the same docker run --health-cmd locally to confirm it returns 0.
2. Adjust user, database, or port until the check passes.

How to prevent it

• Always quote multi-word health-cmd and add interval/retries.
• Validate the health command outside Actions first.

Related guides