Maaz Zindani

Loading the index…

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

sail up fails because Docker cannot find the project's compose file

Errorno configuration file provided: not found

Short answer

Sail is a thin wrapper around Docker Compose, and Compose found no compose file to read. Sail's file is compose.yaml at the project root. Run the command from that folder, publish the file with php artisan sail:install if the project never had one, and clear any COMPOSE_FILE variable that points somewhere else.

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

Fix it fast

  1. 1Find out which cause you have

    Check whether the folder you are standing in has a Sail compose file, and whether the shell has a COMPOSE_FILE value set.

    pwd
    ls -1 compose.yaml docker-compose.yml vendor/bin/sail
    echo "COMPOSE_FILE=$COMPOSE_FILE"
  2. 2Match what you see, then jump to its fix

    1. 1pwd shows a folder such as app/, public/ or your home directory, and ls finds no compose.yamlThe command runs outside the Laravel project folderFix
    2. 2ls shows no compose.yaml in the project root, but vendor/bin/sail may not exist eitherSail was never installed into this projectFix
    3. 3echo $COMPOSE_FILE prints a path, or an old shell profile exports oneCOMPOSE_FILE or -f points at a file that does not existFix

What does the error look like?

  • no configuration file provided: not found

Cause 1 of 3

The command runs outside the Laravel project folder

1Check

Sail's compose file lives at the root of the project, next to the sail script. Compose looks in the current directory and its parents, so a folder above the project, or a sibling, finds nothing.

pwd
ls compose.yaml

2Fix

Change into the project root and run Sail from there.

cd ~/projects/my-app
./vendor/bin/sail up -d

3Verify

The containers list as running.

./vendor/bin/sail ps

Confirmed by laravel.com

Did this fix it?

Cause 2 of 3

Sail was never installed into this project

1Check

Applications created before Sail was added, or created without it, have no compose file. Sail is installed with Composer and then publishes the file.

ls compose.yaml
composer show laravel/sail

2Fix

Install the package, publish the compose file and start the containers. If Composer is not on the host machine, install dependencies another way first.

composer require laravel/sail --dev
php artisan sail:install
./vendor/bin/sail up -d

3Verify

The compose file now exists and Sail starts.

ls compose.yaml
./vendor/bin/sail ps

Confirmed by laravel.com

Did this fix it?

Cause 3 of 3

COMPOSE_FILE or -f points at a file that does not exist

1Check

Compose can take its file from the COMPOSE_FILE environment variable or from -f. A leftover value from another project overrides the search of the current folder.

echo "$COMPOSE_FILE"
grep -n "COMPOSE_FILE" ~/.bashrc ~/.zshrc ~/.profile 2>/dev/null

2Fix

Unset the variable for this shell, remove it from the profile that exports it, or give the correct path with -f.

unset COMPOSE_FILE
docker compose -f compose.yaml config --quiet

3Verify

Sail starts without the error.

./vendor/bin/sail up -d

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Keep compose.yaml committed in the repository so every clone has it.
  • Run Sail commands from the project root, or set the documented shell alias so you do not type the path.
  • Avoid exporting COMPOSE_FILE in a shell profile; set it per project instead.

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

Next step

Want this handled for good?

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