docker compose says invalid compose project
invalid compose projectShort answer
invalid compose project is a wrapper: the real reason is in the text before it. Run docker compose config to see it. Two common reasons are a project name with characters Compose does not allow, such as a folder with capitals or spaces, and a service that has neither an image nor a build section.
Fix it fast
1Find out which cause you have
Validate the file and read the full message. The sentence before the words invalid compose project names the cause.
docker compose config --quiet2Match what you see, then jump to its fix
What does the error look like?
invalid compose projectdocker compose up or config stops with a message that ends in invalid compose projectthe same file worked in another folder, or only fails after you add a new service
Cause 1 of 2
The project name has characters Compose does not allow
1Check
Compose takes the project name from -p, COMPOSE_PROJECT_NAME, the top-level name: key, or the folder name, in that order. A name may contain only lowercase letters, digits, dashes and underscores, and must start with a letter or digit.
pwd
echo "$COMPOSE_PROJECT_NAME"
grep -n "^name:" compose.yaml2Fix
Set a valid name once in the file, or pass one on the command line.
# compose.yaml
name: my-app
services:
web:
image: nginx:1.27
# or on the command line
# docker compose -p my-app up -d3Verify
The config now prints without an error.
docker compose config --quiet && echo okConfirmed by docs.docker.com
Cause 2 of 2
A service has neither image nor build
1Check
The services reference says image may be left out only when a build section is declared. List the services and look for the one with neither.
docker compose config --services2Fix
Give the service an image, or a build context.
services:
api:
build: .
db:
image: postgres:173Verify
Validate again.
docker compose config --quiet && echo okConfirmed by docs.docker.com
How do I stop it coming back?
- Put name: in the Compose file so the project name does not depend on the folder.
- Run docker compose config --quiet in CI before docker compose up.
- Avoid spaces and capital letters in folder names that hold Compose projects.
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
Servers
Compose rejects the top-level name: key in docker-compose.yml
You might be seeing this error because you're using the wrong Compose file version.
A top-level name: sets the Compose project name, but only the Compose Specification tools read it.
3 causes, each with a fixServers
apk cannot find py-pip in an Alpine Docker image
py-pip (no such package):
On current Alpine releases there is no package called py-pip.
2 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
AH00558: Apache in Docker cannot reliably determine its fully qualified domain name
Set the 'ServerName' directive globally to suppress this message
AH00558 is a warning, not a crash.
2 causes, each with a fixServers
Apache in a Docker container logs AH01114 when it proxies to a backend
AH01114: HTTP: failed to make connection to backend: api
Apache's proxy worker could not open a connection to the address in ProxyPass.
5 causes, each with a fix