Docker "HEALTHCHECK interval invalid" build error in CI

By Kaveh Alemi·Latchkey

HEALTHCHECK duration flags (--interval, --timeout, --start-period, --retries) must be valid Go durations with a unit. A bare number, a missing unit, or a value below the 1ms minimum makes the build reject the instruction.

What this error means

A build fails at a HEALTHCHECK line with an invalid duration message. The interval or timeout lacks a unit or is malformed.

ERROR: failed to solve: dockerfile parse error: time: missing unit in duration "30"
# from: HEALTHCHECK --interval=30 CMD curl -f http://localhost/ || exit 1

Common causes

A duration without a unit

A value like 30 is invalid; durations must be 30s, 1m, 500ms, etc.

A value below the 1ms minimum

Intervals and timeouts must be at least 1ms; smaller values are rejected.

How to fix it

Use valid duration units

1. Add a unit to every duration flag.
2. Use --retries as an integer, not a duration.

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD curl -f http://localhost/health || exit 1

Keep durations above the minimum

1. Ensure interval/timeout are at least 1ms (use seconds in practice).

HEALTHCHECK --interval=10s --timeout=2s CMD wget -qO- localhost:8080 || exit 1

How to prevent it

• Always include a time unit on duration flags.
• Use realistic intervals (seconds), not sub-ms values.
• Lint Dockerfiles for HEALTHCHECK syntax.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation