Maaz Zindani

Loading the index…

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

docker compose says invalid compose project

Errorinvalid compose project

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

  • Applies to Docker Compose 2.40, Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1an error that mentions the project name, often after cloning into a folder such as My AppThe project name has characters Compose does not allowFix
    2. 2the message names a service and says it has no image or build contextA service has neither image nor buildFix

What does the error look like?

  • invalid compose project
  • docker compose up or config stops with a message that ends in invalid compose project
  • the 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.yaml

2Fix

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 -d

3Verify

The config now prints without an error.

docker compose config --quiet && echo ok

Confirmed by docs.docker.com

Did this fix it?

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 --services

2Fix

Give the service an image, or a build context.

services:
  api:
    build: .
  db:
    image: postgres:17

3Verify

Validate again.

docker compose config --quiet && echo ok

Confirmed by docs.docker.com

Did this fix it?

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

Next step

Want this handled for good?

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