sail up fails with a permission error
permission deniedShort answer
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. Find which with the first command, then apply the fix below.
Fix it fast
1Find out which cause you have
Read the first lines of the failure and run the context and group checks. The text before 'permission denied' names the file or socket involved.
docker context ls id -nG ls -ld ~/.docker2Match what you see, then jump to its fix
- 1
Error loading config file ... ~/.docker/config.json ... permission deniedDocker's config folder is owned by root after an earlier sudo dockerFix - 2
docker commands work only with sudo, and the group list from id -nG has no dockerYour user is not allowed to run Docker without sudoFix - 3
You use Docker Desktop for Linux, and either Sail will not start or the container reports file permission errorsDocker Desktop for Linux uses a non-default context, or the container user cannot write project filesFix
- 1
What does the error look like?
permission deniedWARNING: Error loading config file: /home/user/.docker/config.json - stat /home/user/.docker/config.json: permission denied
Cause 1 of 3
Docker's config folder is owned by root after an earlier sudo docker
1Check
The Docker docs attribute this warning to wrong permissions on ~/.docker, left behind when Docker commands were run with sudo.
ls -ld ~/.docker ~/.docker/config.json2Fix
Give the folder back to your own user. Removing the folder also works, but you lose custom Docker settings.
sudo chown "$USER":"$USER" /home/"$USER"/.docker -R
sudo chmod g+rwx "$HOME/.docker" -R3Verify
Start Sail again.
./vendor/bin/sail up -dConfirmed by docs.docker.com
Cause 2 of 3
Your user is not allowed to run Docker without sudo
1Check
On Linux, Docker is managed as a non-root user through a docker group. The first command's group list shows whether you are in it.
id -nG | tr ' ' '\n' | grep -x docker2Fix
Create the group if needed, add your user, and refresh your group membership.
sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker3Verify
Run a test container without sudo, then start Sail.
docker run hello-world
./vendor/bin/sail up -dConfirmed by docs.docker.com
Cause 3 of 3
Docker Desktop for Linux uses a non-default context, or the container user cannot write project files
1Check
The Laravel docs say that with Docker Desktop for Linux you should use the default Docker context, and that file permission errors inside containers may need SUPERVISOR_PHP_USER set to root.
docker context ls2Fix
Switch to the default context. If file errors continue, set the variable in .env and restart Sail.
docker context use default
# .env
SUPERVISOR_PHP_USER=root3Verify
Stop and start the containers again.
./vendor/bin/sail down
./vendor/bin/sail up -dConfirmed by laravel.com
How do I stop it coming back?
- Never mix sudo docker and plain docker on the same machine. It is what leaves root-owned files in ~/.docker.
- Add your user to the docker group once, and log out and in again.
- After changing Sail settings, rebuild with sail build --no-cache before starting.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- Spotless LaundryAn on-demand laundry app: Flutter on a Laravel back end, with Firebase for live updates.
Related fixes
Back end
Sail image build stops at groupadd with an invalid group ID
The sail build works through ./vendor/bin/sail but not through plain docker compose
The Sail Dockerfile runs groupadd with the WWWGROUP build argument.
2 causes, each with a fixBack end
sail up fails because Docker cannot find the project's compose file
no configuration file provided: not found
Sail is a thin wrapper around Docker Compose, and Compose found no compose file to read.
3 causes, each with a fixBack end
Composer says the gd extension is missing on a Laravel project
composer install or composer update stops on a package that requires ext-gd
Composer refuses to install a package that requires ext-gd when the PHP binary running Composer has no GD extension.
4 causes, each with a fixBack 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 fixBack end
.NET in Docker cannot load libldap for LDAP or Active Directory
Unable to load shared library 'libldap-2.5.so.0' or one of its dependencies
On Linux, .NET's LDAP code loads the OpenLDAP library at run time, and the .NET images do not ship it.
2 causes, each with a fixBack 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