[BUG] Healthcheck `start_interval` is not respected

[tvardero]

Description

start_interval is not working on container startup, interval is used instead for the first health check.

This creates a long wait time for containers startup with chained dependencies: where service B waits for service A to be healthy, then service C waits for services B to be healthy, and so on.

Using short interval instead of start_interval is a workaround, however this adds more stress to the container in runtime.

Steps To Reproduce

As an example, start postgres (or any other container), with healthcheck interval as 5 seconds.

services:
  postgres:
    image: 'postgres:latest'
    environment:
      - "POSTGRES_PASSWORD=${POSTGRES_PASSWORD}"
    volumes:
      - 'vol-postgres:/var/lib/postgresql/data/'
    healthcheck:
      interval: 5s
      test: [ 'CMD', 'pg_isready', '-U', 'postgres' ]
    restart: on-failure:3

Container will be considered healthy in 5 seconds:

$ docker compose up --detach --wait postgres
[+] Running 1/1
 ✔ Container greatlabmicroservices-postgres-1  Healthy     6.3s

However if you use start_interval as 5 seconds, without specifying interval, then 30 seconds will pass - start_interval does not work and interval default value is 30 seconds.

services:
  postgres:
    image: 'postgres:latest'
    environment:
      - "POSTGRES_PASSWORD=${POSTGRES_PASSWORD}"
    volumes:
      - 'vol-postgres:/var/lib/postgresql/data/'
    healthcheck:
      start_interval: 5s
      test: [ 'CMD', 'pg_isready', '-U', 'postgres' ]
    restart: on-failure:3

$ docker compose up --detach --wait postgres
[+] Running 1/1
 ✔ Container greatlabmicroservices-postgres-1  Healthy     31.2s

Compose Version

Docker Compose version v2.34.0-desktop.1
Docker Desktop 4.40.0 (187762)
Win 11 Pro 24H2 26100.3775
WSL 2.3.26.0

Docker Environment

Client:
 Version:    28.0.4
 Context:    desktop-linux
 Debug Mode: false
 Plugins:
  ai: Docker AI Agent - Ask Gordon (Docker Inc.)
    Version:  v1.1.3
    Path:     C:\Program Files\Docker\cli-plugins\docker-ai.exe
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.22.0-desktop.1
    Path:     C:\Program Files\Docker\cli-plugins\docker-buildx.exe
  cloud: Docker Cloud (Docker Inc.)
    Version:  0.2.20
    Path:     C:\Program Files\Docker\cli-plugins\docker-cloud.exe
  compose: Docker Compose (Docker Inc.)
    Version:  v2.34.0-desktop.1
    Path:     C:\Program Files\Docker\cli-plugins\docker-compose.exe
  debug: Get a shell into any image or container (Docker Inc.)
    Version:  0.0.38
    Path:     C:\Program Files\Docker\cli-plugins\docker-debug.exe
  desktop: Docker Desktop commands (Beta) (Docker Inc.)
    Version:  v0.1.6
    Path:     C:\Program Files\Docker\cli-plugins\docker-desktop.exe
  dev: Docker Dev Environments (Docker Inc.)
    Version:  v0.1.2
    Path:     C:\Program Files\Docker\cli-plugins\docker-dev.exe
  extension: Manages Docker extensions (Docker Inc.)
    Version:  v0.2.27
    Path:     C:\Program Files\Docker\cli-plugins\docker-extension.exe
  init: Creates Docker-related starter files for your project (Docker Inc.)
    Version:  v1.4.0
    Path:     C:\Program Files\Docker\cli-plugins\docker-init.exe
  sbom: View the packaged-based Software Bill Of Materials (SBOM) for an image (Anchore Inc.)
    Version:  0.6.0
    Path:     C:\Program Files\Docker\cli-plugins\docker-sbom.exe
  scout: Docker Scout (Docker Inc.)
    Version:  v1.17.0
    Path:     C:\Program Files\Docker\cli-plugins\docker-scout.exe

Server:
 Containers: 0
  Running: 0
  Paused: 0
  Stopped: 0
 Images: 9
 Server Version: 28.0.4
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Using metacopy: false
  Native Overlay Diff: true
  userxattr: false
 Logging Driver: json-file
 Cgroup Driver: cgroupfs
 Cgroup Version: 1
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
 CDI spec directories:
  /etc/cdi
  /var/run/cdi
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 nvidia runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: 753481ec61c7c8955a23d6ff7bc8e4daed455734
 runc version: v1.2.5-0-g59923ef
 init version: de40ad0
 Security Options:
  seccomp
   Profile: unconfined
 Kernel Version: 5.15.167.4-microsoft-standard-WSL2
 Operating System: Docker Desktop
 OSType: linux
 Architecture: x86_64
 CPUs: 28
 Total Memory: 31.22GiB
 Name: docker-desktop
 ID: f020cabf-053e-4182-a2c0-42a3a5ab1677
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 HTTP Proxy: http.docker.internal:3128
 HTTPS Proxy: http.docker.internal:3128
 No Proxy: hubproxy.docker.internal
 Labels:
  com.docker.desktop.address=npipe://\\.\pipe\docker_cli
 Experimental: false
 Insecure Registries:
  hubproxy.docker.internal:5555
  ::1/128
  127.0.0.0/8
 Live Restore Enabled: false

WARNING: No blkio throttle.read_bps_device support
WARNING: No blkio throttle.write_bps_device support
WARNING: No blkio throttle.read_iops_device support
WARNING: No blkio throttle.write_iops_device support
WARNING: DOCKER_INSECURE_NO_IPTABLES_RAW is set
WARNING: daemon is not using the default seccomp profile

Anything else?

No response

[ndeloof]

Same applies if you run postgres using docker run:

$ docker run --health-start-interval 5s --health-cmd "pg_isready -U postgres"  -e POSTGRES_PASSWORD=toto -d  postgres 
..
$ docker ps
CONTAINER ID   IMAGE      COMMAND                  CREATED          STATUS                             PORTS      NAMES
eec133a2e302   postgres   "docker-entrypoint.s…"   29 seconds ago   Up 29 seconds (health: starting)   5432/tcp   recursing_chebyshev
$ docker ps
CONTAINER ID   IMAGE      COMMAND                  CREATED          STATUS                    PORTS      NAMES
eec133a2e302   postgres   "docker-entrypoint.s…"   30 seconds ago   Up 30 seconds (healthy)   5432/tcp   recursing_chebyshev

docker events ran in another terminal doesn't report any exec command taking place during the start period as one would expect.

container is well configured:

            "Healthcheck": {
                "Test": [
                    "CMD-SHELL",
                    "pg_isready -U postgres"
                ],
                "Interval": 30000000000,
                "StartInterval": 5000000000
            },

Sounds to me this is a bug in Moby, would you mind reporting this to github.com/moby/moby ?

[tvardero]

@MrQubo have found that start_interval does not work without adding start_period.

I had exactly the same scenario and it also took me some time to find out that the start-period is required for start-interval to work. Silently ignoring start-interval should be considered a bug.

I have tested adding start_period and it works:

services:
  postgres:
    image: 'postgres'
    environment:
      - "POSTGRES_PASSWORD=${POSTGRES_PASSWORD}"
    volumes:
      - 'vol-postgres:/var/lib/postgresql/data/'
    healthcheck:
      start_interval: 5s
      start_period: 30s
      test: [ 'CMD', 'pg_isready', '-U', 'postgres' ]
    restart: on-failure:3

✔ Container greatlabmicroservices-postgres-1            Healthy     7.4s