Compose rejects the top-level name: key in docker-compose.yml
Invalid top-level property "name"Short answer
A top-level name: sets the Compose project name, but only the Compose Specification tools read it. The old Python docker-compose v1 has no name field in its config model and rejects it. Run docker compose (v2), or set the name with -p or COMPOSE_PROJECT_NAME.
Fix it fast
1Find out which cause you have
See which Compose you are calling. The hyphenated command is the old Python tool.
docker-compose version docker compose version2Match what you see, then jump to its fix
- 1
Invalid top-level property "name" from the docker-compose commandThe file is read by the old docker-compose v1Fix - 2
The tool must stay on v1 for nowYou cannot upgrade yet and need a project nameFix - 3
The name is accepted by v2 but the name value has capitals or spacesThe project name has characters Compose does not allowFix
- 1
What does the error look like?
Invalid top-level property "name"You might be seeing this error because you're using the wrong Compose file version.
Cause 1 of 3
The file is read by the old docker-compose v1
1Check
In the v1 code, the parsed config has no name field and only services, volumes, networks, secrets and configs are processed. The top-level name element belongs to the Compose Specification used by v2.
docker-compose version2Fix
Use the v2 plugin. It ships with Docker Desktop, and on Linux it is the docker-compose-plugin package.
docker compose up -d3Verify
docker compose config prints the file with the name at the top.
docker compose config | head -n 3Confirmed by raw.githubusercontent.com
Cause 2 of 3
You cannot upgrade yet and need a project name
1Check
Compose picks the project name by precedence: the -p flag, then COMPOSE_PROJECT_NAME, then the name: in the file, then the directory name.
echo "$COMPOSE_PROJECT_NAME"2Fix
Delete the name: line from the file and give the name on the command line or in the environment.
docker-compose -p myproject up -d
# or
export COMPOSE_PROJECT_NAME=myproject3Verify
The containers are created with the chosen prefix.
docker ps --format '{{.Names}}'Confirmed by docs.docker.com
Cause 3 of 3
The project name has characters Compose does not allow
1Check
A project name may hold only lowercase letters, digits, dashes and underscores, and must start with a lowercase letter or digit.
grep -n '^name:' docker-compose.yml2Fix
Rewrite the value to match that rule.
name: my-shop_23Verify
Compose accepts the file.
docker compose configConfirmed by docs.docker.com
How do I stop it coming back?
- Standardise on docker compose v2 in documentation and CI.
- Set the name: in the file once so every developer gets the same container prefix.
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 refuses the version line in docker-compose.yml
You might be seeing this error because you're using the wrong Compose file version.
This error comes from the old Python docker-compose v1 tool.
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