Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Sail image build stops at groupadd with an invalid group ID

Errorgroupadd: invalid group ID 'sail'

Short answer

The Sail Dockerfile runs groupadd with the WWWGROUP build argument. If that argument is empty, groupadd receives the word sail where it expects a number and stops. WWWGROUP is normally filled in by the sail script, so the build fails when compose runs without it or when compose.yaml no longer passes it.

  • Applies to Laravel 12, Laravel Sail 1.x, Docker Compose v2, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the group id the sail script would pass, then build through the script instead of calling docker compose yourself.

    id -g
    ./vendor/bin/sail build --no-cache
  2. 2Match what you see, then jump to its fix

    1. 1The build works with ./vendor/bin/sail up but fails with docker compose up --build, from an IDE button, a CI job or a Docker GUI.Docker Compose was started without the sail scriptFix
    2. 2WWWGROUP appears in no build.args block of the laravel.test service.compose.yaml no longer passes WWWGROUP to the buildFix

What does the error look like?

  • groupadd: invalid group ID 'sail'
  • The sail build works through ./vendor/bin/sail but not through plain docker compose

Cause 1 of 2

Docker Compose was started without the sail script

1Check

The sail script exports WWWGROUP from the current user's primary group when it is not already set. A plain docker compose call skips that export, so the build argument is empty and the Dockerfile line groupadd --force -g $WWWGROUP sail becomes groupadd --force -g sail.

echo "WWWGROUP=[$WWWGROUP]"
grep -n "WWWGROUP" compose.yaml

2Fix

Run the build through the sail script. If you must call compose yourself, export the same values first.

export WWWUSER=$(id -u)
export WWWGROUP=$(id -g)
docker compose build --no-cache

3Verify

The build finishes and the containers start.

./vendor/bin/sail up -d

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 2

compose.yaml no longer passes WWWGROUP to the build

1Check

The Laravel docs show WWWGROUP as a build argument of the laravel.test service. After a hand edit, a merge or an old compose.yaml copied from another project, that line may be missing.

grep -n -B3 -A6 "build:" compose.yaml

2Fix

Put the argument back under the build section of laravel.test, or regenerate the file.

build:
    context: ./vendor/laravel/sail/runtimes/8.4
    dockerfile: Dockerfile
    args:
        WWWGROUP: '${WWWGROUP}'

3Verify

Rebuild without the layer cache, as the Sail docs describe.

docker compose down -v
./vendor/bin/sail build --no-cache

Confirmed by laravel.com

Did this fix it?

How do I stop it coming back?

  • Start Sail with ./vendor/bin/sail (or a shell alias for it) so WWWGROUP and WWWUSER are always set.
  • If a tool has to run docker compose for you, set WWWUSER and WWWGROUP in its environment.
  • Keep compose.yaml changes small and review the build.args block after every merge.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

sail up fails with a permission error

WARNING: Error loading config file: /home/user/.docker/config.json - stat /home/user/.docker/config.json: permission denied

A permission error from sail up has three documented sources on Linux: Docker Desktop is using the wrong context, files inside the container are not writable by the container user, or Docker's own config folder is owned by root from an earlier sudo run.

3 causes, each with a fix

Back end

composer require laravel/horizon fails: ext-pcntl is missing

laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system

Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.

3 causes, each with a fix

Back end

Why a Filament panel feels slow on a Laravel server

The panel is fast on a small demo and slow once there are many resources, pages and widgets

A slow Filament panel on a server is most often running without the production caches.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.