Compose "service ... refers to undefined secret" in CI

By Kaveh Alemi·Latchkey

A service secret must reference a secret declared in the top-level secrets: block. If the name under the service has no matching top-level definition, Compose reports it as undefined and refuses to start.

What this error means

A compose command fails with "service \"app\" refers to undefined secret \"db_password\": invalid compose project".

service "app" refers to undefined secret "db_password": invalid compose project

Common causes

No matching top-level secrets entry

The service lists a secret name that is never declared under the top-level secrets: key.

A name mismatch between service and top level

The service references one name while the top-level block declares a slightly different one, so resolution fails.

How to fix it

Declare the secret at the top level

1. Add a top-level secrets: entry whose key matches the service reference.
2. Point it at a file or environment source.
3. Re-run; the secret now resolves.

services:
  app:
    secrets:
      - db_password
secrets:
  db_password:
    file: ./secrets/db_password.txt

Provide the secret source in CI

Write the secret file from a CI secret before running compose so the file-based source exists.

run: |
  mkdir -p secrets
  printf '%s' "${{ secrets.DB_PASSWORD }}" > secrets/db_password.txt
  docker compose up -d

How to prevent it

• Declare every referenced secret in the top-level secrets: block.
• Keep service and top-level secret names identical.
• Materialize secret source files in CI before compose runs.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation