dockerfile parse error unknown flag: start-interval

[mrsarm]

Description

I have a Dockerfile that works fine, and after adding a HEALTHCHECK section almost identical that the one suggested in the official docs with the addition of the --start-interval flag, it does fail with the error:

$ docker build -t myservice:latest .
=> [internal] load .dockerignore
 => => transferring context: 95B
 ...
Dockerfile:39
--------------------
  38 |     
  39 | >>> HEALTHCHECK \
  40 | >>>   --interval=15s \
  41 | >>>   --start-interval=5s \
  42 | >>>   --timeout=5s \
  43 | >>>   CMD /usr/app/bin/backset health
  44 |     
--------------------
ERROR: failed to solve: dockerfile parse error on line 39: unknown flag: start-interval

Reproduce

1. Create a pretty simple image like the following:

   FROM nginx:1.25
   EXPOSE 80
   CMD ["nginx", "-g", "daemon off;"]
   

2. Build the image, no issues:

   $ docker build -t mynginx:latest .
   [+] Building 5.1s (6/6) FINISHED                                                                                                                                                docker:default
   ...
    => => naming to docker.io/library/mynginx:latest
   

3. Add as suggested in the official docs a HEALTHCHECK section as following, no issues so far after build again:

   FROM nginx:1.25
   EXPOSE 80
   CMD ["nginx", "-g", "daemon off;"]
   
   HEALTHCHECK --interval=5m --timeout=3s \
     CMD curl -f http://localhost/ || exit 1
   

4. Now change the HEALTHCHECK adding the start-interval flag that the official documentation says it's supported:

   FROM nginx:1.25
   EXPOSE 80
   CMD ["nginx", "-g", "daemon off;"]
   
   HEALTHCHECK --interval=5m --timeout=3s --start-interval=1m \
     CMD curl -f http://localhost/ || exit 1
   

5. Build again, you get an error like the following:

   $ docker build -t mynginx:latest .
   [+] Building 0.0s (2/2) FINISHED                                                                                                                                                docker:default
    => [internal] load build definition from Dockerfile
    => => transferring dockerfile: 203B
    => [internal] load .dockerignore
    => => transferring context: 2B
   Dockerfile:5
   --------------------
      4 |     
      5 | >>> HEALTHCHECK --interval=5m --timeout=3s --start-interval=6m \
      6 | >>>   CMD curl -f http://localhost/ || exit 1
   --------------------
   ERROR: failed to solve: dockerfile parse error on line 5: unknown flag: start-interval
   

Expected behavior

This section in the docs states that the flag should work:

So the build should be successful in the step 5 as it is in the step 3.

docker version

Client: Docker Engine - Community
 Version:           24.0.5
 API version:       1.43
 Go version:        go1.20.6
 Git commit:        ced0996
 Built:             Fri Jul 21 20:35:23 2023
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          24.0.5
  API version:      1.43 (minimum version 1.12)
  Go version:       go1.20.6
  Git commit:       a61e2b4
  Built:            Fri Jul 21 20:35:23 2023
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.6.22
  GitCommit:        8165feabfdfe38c65b599c4993d227328c231fca
 runc:
  Version:          1.1.8
  GitCommit:        v1.1.8-0-g82f18fe
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

docker info

Client: Docker Engine - Community
 Version:    24.0.5
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.11.2
    Path:     /usr/libexec/docker/cli-plugins/docker-buildx
  compose: Docker Compose (Docker Inc.)
    Version:  v2.18.1
    Path:     /usr/libexec/docker/cli-plugins/docker-compose

Server:
 Containers: 2
  Running: 1
  Paused: 0
  Stopped: 1
 Images: 158
 Server Version: 24.0.5
 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 logentries splunk syslog
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: 8165feabfdfe38c65b599c4993d227328c231fca
 runc version: v1.1.8-0-g82f18fe
 init version: de40ad0
 Security Options:
  apparmor
  seccomp
   Profile: builtin
 Kernel Version: 5.15.0-78-generic
 Operating System: Ubuntu 20.04.6 LTS
 OSType: linux
 Architecture: x86_64
 CPUs: 16
 Total Memory: 30.96GiB
 Name: tpad
 ID: LLKE:P5SX:TI75:L2C4:SHO2:F3M4:3UUF:4IPT:CWZ4:7IJI:EJSI:U2UA
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 Username: mrsarm
 Experimental: false
 Insecure Registries:
  127.0.0.0/8
 Live Restore Enabled: false

Additional Info

No response

[graham2071]

I just encountered the same issue. This feature has been been merged but not yet released. See moby/moby#40894: milestone is 25.0.0.
Maybe the doc should mention the version in which the feature is implemented.

[thaJeztah]

Yes, this is currently expected if you use the default dockerfile syntax that's used by the docker 24.0 (and older) engine.

The new option can be parsed by the latest version of the Dockerfile syntax (aka "frontend"), which has been released (and because of that docs are published) and you can make sure the latest syntax is used by adding a syntax directive to your Dockerfile;

# syntax=docker/dockerfile:1

FROM yourimage:latest
# ... etc

However, the option will not yet take effect on current versions of the docker engine. You can find more details in moby/moby#45897 (comment)

I'll close this ticket, as this is currently expected, but feel free to continue the conversation 👍