Docker "Dockerfile: maximum number of args exceeded" in CI

By Daniel Zoghalchali·Latchkey

Some Dockerfile instructions accept a bounded number of arguments. When an instruction is written with too many tokens - usually a mangled flag, an unquoted multi-word value, or a misformatted exec-form array - the parser stops with "maximum number of args exceeded".

What this error means

A build fails at parse time with dockerfile parse error: ... maximum number of arguments exceeded at a specific instruction line.

Dockerfile:5
--------------------
   5 | >>> STOPSIGNAL SIGTERM SIGKILL
--------------------
ERROR: failed to solve: dockerfile parse error on line 5: STOPSIGNAL maximum number of arguments exceeded

Common causes

An instruction that takes one value got several

Instructions like STOPSIGNAL, USER, or WORKDIR take a single argument; extra tokens overflow the limit.

An unquoted value with spaces

A path or value containing spaces that is not quoted is split into multiple arguments.

A malformed exec-form array

A broken JSON array in CMD/ENTRYPOINT can be reparsed as shell form with too many tokens.

How to fix it

Pass a single, quoted argument

1. Give single-value instructions exactly one token.
2. Quote any value that contains spaces.

STOPSIGNAL SIGTERM
WORKDIR "/opt/my app"

Use valid exec-form JSON for CMD/ENTRYPOINT

1. Write the array with double quotes and no trailing junk.

ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
CMD ["--port", "8080"]

How to prevent it

• Quote multi-word values and keep single-value instructions to one token.
• Lint Dockerfiles (hadolint) in CI to catch arg-count mistakes early.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation