Maaz Zindani

Loading the index…

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

sail up fails with a permission error

Errorpermission denied

Short 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.

  • Applies to Laravel Sail on Ubuntu 24.04, Docker Engine, Docker Desktop for Linux
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 ~/.docker
  2. 2Match what you see, then jump to its fix

    1. 1Error loading config file ... ~/.docker/config.json ... permission deniedDocker's config folder is owned by root after an earlier sudo dockerFix
    2. 2docker 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. 3You 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

What does the error look like?

  • permission denied
  • WARNING: 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.json

2Fix

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" -R

3Verify

Start Sail again.

./vendor/bin/sail up -d

Confirmed by docs.docker.com

Did this fix it?

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 docker

2Fix

Create the group if needed, add your user, and refresh your group membership.

sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker

3Verify

Run a test container without sudo, then start Sail.

docker run hello-world
./vendor/bin/sail up -d

Confirmed by docs.docker.com

Did this fix it?

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 ls

2Fix

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=root

3Verify

Stop and start the containers again.

./vendor/bin/sail down
./vendor/bin/sail up -d

Confirmed by laravel.com

Did this fix it?

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:

Related fixes

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.