Compose "invalid project name" in CI

By Daniel Zoghalchali·Latchkey

Compose derives a project name from the directory or the -p/COMPOSE_PROJECT_NAME value and validates it. The name must be lowercase alphanumerics, hyphens, and underscores, and start with a letter or number; anything else is rejected.

What this error means

A compose command fails with "invalid project name \"<name>\": must consist only of lowercase alphanumeric characters, hyphens, and underscores as well as start with a letter or number".

invalid project name "My_App.CI": must consist only of lowercase alphanumeric
characters, hyphens, and underscores as well as start with a letter or number

Common causes

Uppercase or special characters in the name

A -p value or branch-derived name with capitals, dots, or slashes violates the allowed character set.

A name derived from a ref with illegal characters

Using ${{ github.ref_name }} directly can include slashes or dots that are not valid project-name characters.

How to fix it

Use a valid lowercase project name

1. Lowercase the name and replace dots/slashes with hyphens or underscores.
2. Pass it with -p or COMPOSE_PROJECT_NAME.
3. Re-run; the name now passes validation.

COMPOSE_PROJECT_NAME=myapp-ci docker compose up -d

Sanitize a derived name

Normalize a branch or ref into a valid name before passing it to Compose.

name="$(echo "${{ github.ref_name }}" | tr 'A-Z/.' 'a-z--')"
COMPOSE_PROJECT_NAME="app-$name" docker compose up -d

How to prevent it

• Keep project names lowercase alphanumeric with hyphens/underscores.
• Sanitize any ref-derived name before using it.
• Set COMPOSE_PROJECT_NAME explicitly in CI.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation