This error occurs when Docker Compose cannot find or access the build context directory specified in your docker-compose.yml file. The build context path may be misspelled, point to a non-existent directory, use incorrect relative paths, or have permission restrictions preventing access.
When Docker Compose reads your `docker-compose.yml` file and encounters a service with a `build:` configuration, it needs to locate the build context directory. This directory contains the Dockerfile and any files that will be available during the image build process. The error "build path either does not exist, is not accessible, or is not a valid URL" indicates that Compose cannot find or access this directory. The build context path is resolved relative to the location of the `docker-compose.yml` file by default. If you specify `context: ./backend`, Compose looks for a directory named `backend` in the same folder as your compose file. Common issues include: - **Typos or case sensitivity**: On Linux, `./Backend` is different from `./backend` - **Wrong working directory**: Running `docker-compose` from a different directory than expected - **Missing directories**: The directory genuinely doesn't exist (perhaps not created yet, or deleted) - **Permission issues**: The directory exists but the current user cannot read it - **Multiple compose files**: When using `-f` flags with compose files in different directories, path resolution can be confusing This error prevents Docker Compose from proceeding with any commands that need to validate the build configuration, including `docker-compose config`, `docker-compose build`, and even `docker-compose up` when the service needs building.
First, check if the directory specified in your build: section actually exists. Look at your docker-compose.yml:
services:
myservice:
build:
context: ./backend # Check this path
dockerfile: DockerfileThen verify the directory exists relative to your compose file:
# List the directory contents
ls -la ./backend
# Or check if directory exists
test -d ./backend && echo "Directory exists" || echo "Directory NOT found"If using the shorthand build: ./backend, the same applies - verify ./backend exists.
Docker Compose resolves relative paths from the directory containing the compose file, not your current working directory. This is a common source of confusion.
# Show current directory
pwd
# Find where your compose file is
ls -la docker-compose.yml
# Run compose from the correct directory
cd /path/to/project
docker-compose buildIf you're using the -f flag to specify a compose file in a different location, paths are still resolved relative to that file:
# This resolves paths relative to /other/path/, not current directory
docker-compose -f /other/path/docker-compose.yml buildCorrect the path if it's wrong. Use relative paths for portability:
# WRONG - absolute path, not portable
services:
web:
build:
context: /Users/john/projects/myapp/backend
# CORRECT - relative path from compose file location
services:
web:
build:
context: ./backend
dockerfile: DockerfileFor the current directory as build context:
services:
web:
build:
context: .
dockerfile: DockerfileIf your Dockerfile is in a subdirectory:
services:
web:
build:
context: .
dockerfile: backend/DockerfileWhen using multiple compose files with -f, all relative paths are resolved from the first file's directory:
# base.yml is in /project/compose/
# override.yml is in /project/compose/overrides/
docker-compose -f /project/compose/base.yml -f /project/compose/overrides/override.yml upIn this case, build contexts in both files resolve relative to /project/compose/.
If this causes issues, restructure to use a common base directory:
# In override.yml, adjust paths knowing resolution starts from base.yml location
services:
web:
build:
context: ../app # Goes up from compose/, then into app/Or use the COMPOSE_FILE environment variable:
export COMPOSE_FILE=docker-compose.yml:docker-compose.override.yml
docker-compose upIf the directory exists but you still get "is not accessible", check permissions:
# Check permissions on the directory
ls -la ./backend
# You should see at least read and execute permissions (r-x)
# drwxr-xr-x 5 user group 160 Jan 15 10:00 backend
# Fix permissions if needed
chmod 755 ./backend
# For permission issues on Linux, also check if running as correct user
whoami
ls -la /var/run/docker.sockOn SELinux-enabled systems, you may need to adjust security contexts:
# Check current context
ls -Z ./backend
# Allow Docker to read the directory
chcon -Rt svirt_sandbox_file_t ./backendIf the directory should exist but doesn't (common in fresh git clones or CI environments):
# Create the directory
mkdir -p ./backend
# If it should contain a Dockerfile, create it
touch ./backend/DockerfileIn CI/CD pipelines, ensure the directory is created before running compose:
# GitHub Actions example
- name: Create required directories
run: mkdir -p ./backend
- name: Docker Compose Build
run: docker-compose buildIf using git, check if the directory was accidentally excluded:
# Check .gitignore
cat .gitignore | grep backend
# Check if directory is tracked
git ls-files ./backendIn older Docker Compose versions, the build path was validated even when using --no-build. If you want to use pre-built images without the build context present:
# Option 1: Use separate compose files for build vs deploy
# docker-compose.build.yml (for building)
services:
web:
build:
context: ./backend
# docker-compose.yml (for deployment)
services:
web:
image: myregistry/myapp:latest# For building
docker-compose -f docker-compose.build.yml build
# For deployment (no build context needed)
docker-compose upOption 2: Create a placeholder directory in CI/CD:
# Create minimal placeholder to pass validation
mkdir -p ./backend
echo "FROM scratch" > ./backend/Dockerfile
docker-compose up --no-buildThis workaround is fixed in newer Compose versions where --no-build properly skips build context validation.
Path resolution in Docker Compose: Understanding how Compose resolves paths is crucial:
1. Relative paths: Always relative to the compose file location, not pwd
2. Environment variable substitution: Paths can use env vars: context: ${BUILD_DIR:-./default}
3. Build vs runtime: Build context is only needed at build time, not when running pre-built images
Cross-platform path issues: On Windows with WSL2 or Git Bash:
# May fail on Windows
context: ./backend
# Works on Windows - use forward slashes
context: ./backend
# Absolute Windows paths need special handling
# WRONG: context: C:\Users\john\project\backend
# Use WSL path or relative path insteadDocker Compose V2 changes: The newer docker compose (V2, written in Go) handles some edge cases differently than the older docker-compose (V1, written in Python):
# Check which version you're using
docker compose version
docker-compose --version
# V2 is more lenient with --no-build flag
docker compose up --no-buildRemote build contexts: Docker Compose supports Git URLs as build contexts:
services:
web:
build:
context: https://github.com/user/repo.git#branch:subdirectoryIf this fails with "not a valid URL", ensure:
- The URL is accessible (public repo or with credentials)
- The format is correct: URL#branch:path
- You have git installed and accessible
Debugging compose file parsing:
# Validate and display the resolved config
docker compose config
# Show which file is being used
docker compose config --resolve-image-digests 2>&1 | head -20
# Use verbose mode for more details
docker compose --verbose buildimage operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub