[BonusPlay]

The gotcha is that "global" args don't propagate automatically to all stages (thin includes 1 stage builds).

I want this one arg in multiple stages, so I'll declare it above everything is the chain of thought.

[koito17]

I interpret each directive in a Dockerfile as creating a new layer of an image. So this ARG-before-FROM gotcha doesn't feel like a gotcha to me, but rather, the consequence of literally interpreting "ARG" and not knowing the side-effects of a directive in a Dockerfile. (Yes, even WORKDIR, ENTRYPOINT, and related instructions create a layer, albeit a 0-byte one)

[fireflash38]

It persists across every other new layer. It just doesn't persist across FROM.

[johanbcn]

It's explained on the official documentation: https://docs.docker.com/reference/dockerfile/#scope

[hombre_fatal]

True, though gotchas exist when user intuition doesn't match with actual behavior regardless of whether they are mentioned in docs.

[chii]

Principle of least surprise.

If you need to write in the docs about a surprise that a user otherwise wouldn't have expected, may be it's a sign that the surprise should be fixed up such that it's not surprising behaviour.