Let's use this Dockerfile above (notice the typo with the useradd command):

FROM ubuntu:latest

RUN groupadd -r mtitek --gid=1001 && userad -r -g mtitek --uid=1001 mtitek

Let's build the Dockerfile:

$ DOCKER_BUILDKIT=0 docker build -t ubuntu-nginx:latest .

Sending build context to Docker daemon  2.048kB

Step 1/2 : FROM ubuntu:latest
 ---> 1e4467b07108

Step 2/2 : RUN groupadd -r mtitek --gid=1001 && userad -r -g mtitek --uid=1001 mtitek
 ---> Running in b27947fe0a34
/bin/sh: 1: userad: not found
The command '/bin/sh -c groupadd -r mtitek --gid=1001 && userad -r -g mtitek --uid=1001 mtitek' returned a non-zero code: 127

In this case we can see the build complains about the command 'userad'.

In some cases the error might not be very clear from the build output, so a nice feature in Docker is that you can use an intermediate layer of the image to start a container and debug any failing command.

For example, we can run a container from the created layer '1e4467b07108' (see above) and execute commands directly in the container:

$ docker container run --rm -it 1e4467b07108 /bin/bash

root@31367b5e6cf0:/# groupadd -r mtitek --gid=1001 && userad -r -g mtitek --uid=1001 mtitek
bash: userad: command not found