Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Compose rejects the top-level name: key in docker-compose.yml

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

  • Applies to Docker Compose v2, docker-compose v1
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1Invalid top-level property "name" from the docker-compose commandThe file is read by the old docker-compose v1Fix
    2. 2The tool must stay on v1 for nowYou cannot upgrade yet and need a project nameFix
    3. 3The name is accepted by v2 but the name value has capitals or spacesThe project name has characters Compose does not allowFix

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 version

2Fix

Use the v2 plugin. It ships with Docker Desktop, and on Linux it is the docker-compose-plugin package.

docker compose up -d

3Verify

docker compose config prints the file with the name at the top.

docker compose config | head -n 3

Confirmed by raw.githubusercontent.com

Did this fix it?

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

3Verify

The containers are created with the chosen prefix.

docker ps --format '{{.Names}}'

Confirmed by docs.docker.com

Did this fix it?

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

2Fix

Rewrite the value to match that rule.

name: my-shop_2

3Verify

Compose accepts the file.

docker compose config

Confirmed by docs.docker.com

Did this fix it?

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

Next step

Want this handled for good?

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