Laravel Sail won't build on Ubuntu 20.04 - groupadd: invalid group ID 'sail'
If you are attempting to spin up a fresh Laravel application on Ubuntu 20.04 using Docker Compose via ./vendor/bin/sail, you might encounter a specific failure during the initial container build. The error message is explicit: groupadd: invalid group ID 'sail'.
This issue stems from how the official Laravel Sail installation script interacts with your host system's user configuration. When running the standard setup command, the script attempts to create a new Unix group named sail and add your current user to it. This mechanism is essential for volume mounting; it allows containers to write to the host directory without requiring root privileges, ensuring that files created inside the container (like storage or logs) are owned correctly on your filesystem.
However, Ubuntu 20.04 has a known behavior regarding group IDs. If you have previously run Sail commands or if a previous attempt at installation left behind a stale configuration, the group ID for the name sail might already be claimed by a different group (or simply reserved), causing the groupadd --force command inside the Docker build context to fail. The build process halts because it cannot establish the necessary permissions for the web server user inside the container to access your project files.
The solution is straightforward but requires modifying the local Docker Compose file before running the up command. You need to explicitly tell Sail to skip the automatic group creation step and instead rely on the existing system groups or a predefined group ID that matches your host environment.
Open your docker-compose.yml file (usually located in the root of your project) and locate the service definition for laravel.test. You will see an extra_hosts or a custom build argument section, but often the fix lies in how the image is built. The specific workaround involves adding a build argument to override the group creation logic.
Add the following arguments to your docker-compose.yml:
services:
laravel.test:
build:
context: ./vendor/laravel/sail/runtimes/8.1 # Adjust version as needed
args:
WWWGROUP: '${WWWGROUP:-1000}'
SAIL_USER_ID: '${SAIL_USER_ID:-1000}'
SAIL_GROUP_ID: '${SAIL_GROUP_ID:-1000}'
Wait, there is a simpler approach that avoids complex build args if the issue is strictly the groupadd command failing due to an existing group. The most direct fix for Ubuntu 20.04 is to ensure the user and group IDs match before running Sail. However, since the error specifically mentions groupadd --force, it implies the script expects the group not to exist or fails when forcing a creation on an ID that is taken.
A more reliable method that developers often use when facing this specific "invalid group ID" error is to manually create the group and user on the host machine with a known ID, or simply skip the automatic creation by setting the WWWGROUP variable to match your current primary group ID if you are not using rootless mode.
But there is a nuance here: the official Laravel documentation suggests running composer install first. If you have already done that and the error persists, it indicates the Docker build context is failing. The specific line causing the crash is /bin/sh -c groupadd --force -g $WWWGROUP sail. This command tries to force-add a group with GID $WWWGROUP. On Ubuntu 20.04, if the system already has a group with that GID (which happens if you have used Sail before), groupadd without specific flags might complain, but the error says "invalid group ID", which usually means the ID is out of range or already taken by something else that isn't named 'sail'.
The most effective fix is to edit your docker-compose.yml to explicitly define the user and group IDs. Open your docker-compose.yml and ensure you have the following variables set at the top level or within the service arguments:
x-aliases:
sail:
- ./vendor/bin/sail up
- ./vendor/bin/sail down
- ./vendor/bin/sail logs
- ./vendor/bin/sail shell
- ./vendor/bin/sail exec
- ./vendor/bin/sail publish
services:
laravel.test:
build:
context: ../
dockerfile: Dockerfile
args:
WWWGROUP: '${WWWGROUP:-1000}'
Then, in your terminal, set the environment variable before running sail up:
export WWWGROUP=1000
sail up --build
If you are on Ubuntu 20.04 and the default GID is different (e.g., 999 or 1001), calculate your current primary group ID using id -g. If your primary group ID is not 1000, set WWWGROUP to that value:
echo $UID # Should match the user ID
echo $GID # Should match the group ID
export WWWGROUP=$GID
sail up --build
By forcing the GID to match your existing system user's primary group, you bypass the need for Sail to create a new group entirely, effectively sidestepping the groupadd command that is failing. This ensures that the volume mounts are handled by your existing user context rather than creating a conflicting entrypoint.
If you are following the Laravel 8 installation guide, note that this behavior is consistent with how Docker handles file permissions on Linux distributions that pre-configure specific GIDs. Always verify your host environment's id output before assuming default values like 1000 will work universally without configuration.