GitHub Actions "service container is not healthy"

By Kaveh Alemi·Latchkey

A service container defines a health check, but it never reaches a healthy state within the runner timeout, so the job is aborted at initialization. On Latchkey managed runners, transient service-startup failures are auto-retried and warm pools shorten the cold-start window that often causes flaky health checks.

What this error means

The "Initialize containers" phase fails reporting that a named service container is not healthy.

##[error]Failed to initialize container postgres:16
Error: The container 'postgres' in your job is not healthy.

Common causes

Health check command is wrong

The configured health check probes a command or port the service does not expose yet, so it never passes.

Service needs more startup time

The default retries and interval expire before a slow service (database, search engine) finishes initializing.

Missing required environment

The service exits early because a required env var (for example a database password) was not provided.

How to fix it

Tune the health check and env

1. Provide the service its required environment variables.
2. Set a health check that matches how the service signals readiness, with generous retries and a start period.
3. Re-run.

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

How to prevent it

• Always pass required env to service containers so they start cleanly.
• Give slow services a start period and ample health retries.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions