Dockerfile "useradd: user already exists" in CI

By Kaveh Alemi·Latchkey

A RUN useradd or RUN groupadd failed because the name already exists. Many language base images (node, postgres, www-data) ship a predefined user, so re-creating it aborts the step.

What this error means

A RUN step fails with "useradd: user 'node' already exists" or "groupadd: group 'app' already exists" (Debian adduser prints "The user 'X' already exists. Exiting.").

docker build

useradd: user 'node' already exists
The command '/bin/sh -c useradd -m node' returned a non-zero code: 1

Common causes

The base image predefines the user or group

Images like node already include a node user and group, so a second useradd node collides with the existing entry.

A duplicate UID or GID collision

Re-using an in-use UID or GID triggers a related failure such as "useradd: UID N is not unique" or "addgroup: gid N in use".

How to fix it

Guard creation so it is idempotent

Only create the user or group when it is not already present.

Dockerfile

RUN getent group app || groupadd app
RUN id -u app >/dev/null 2>&1 || useradd -g app app

Reuse the predefined account

Check the base image docs for an existing non-root user.
Switch to it with USER node instead of creating a new one.
Only add a user when the image truly has none.

Dockerfile

USER node

How to prevent it

Check whether the base image already ships a non-root user.
Guard useradd/groupadd with an existence check.
Pick a non-colliding name and UID when you must add one.

Frequently asked questions

What causes ""useradd: user already exists""?

Images like node already include a node user and group, so a second useradd node collides with the existing entry.

How do I fix "useradd: user already exists"?