Fix “profiles not found” and misused Docker Compose profiles

What this error means

The error profiles "…" not found appears when you enable a profile (via --profile or COMPOSE_PROFILES) that does not exist on any service in the final Compose configuration. It can also show up when profiles are defined incorrectly or in the wrong place.

This guide shows how to diagnose and fix it, plus how to use Compose profiles correctly.

Quickstart: the shortest path to green

1. Verify Compose version supports profiles

• Run: docker compose version (or docker-compose version)
• Profiles require Docker Compose v1.28+ (or Compose plugin v2+).

1. Inspect the effective config to see actual profiles

• Run: docker compose config | grep -n "profiles:"
• If nothing appears, you have no profiles in your services.

1. Use the exact profile names that exist

• Enable with CLI: docker compose --profile dev up
• Or env var: COMPOSE_PROFILES=dev,worker docker compose up

1. Fix invalid YAML placement/types

• profiles must be a list under services.<name>.
• Do not use a top-level profiles key.

1. Combine files consistently if you split your stack

• If a service with a profile lives in a second file, pass it: docker compose -f compose.yml -f compose.dev.yml --profile dev up

Minimal working example (MWE)

compose.yml:

version: "3.9"
services:
  web:
    image: nginx:alpine
    # No profiles -> always included unless excluded by selection logic

  worker:
    image: alpine
    command: ["sh", "-c", "echo worker running; sleep 3600"]
    profiles: ["worker"]

  debug:
    image: alpine
    command: ["sh", "-c", "echo debug shell; sleep 3600"]
    profiles: ["debug"]

Common runs:

# Default: starts only services without profiles (web)
docker compose up -d

# Enable worker (starts web + worker)
docker compose --profile worker up -d

# Enable multiple profiles
docker compose --profile worker --profile debug up -d

# Using env var (comma-separated)
COMPOSE_PROFILES=worker,debug docker compose up -d

Triggering the error:

# There is no profile named "dev" in the file above
docker compose --profile dev up
# -> error: profiles "dev" not found

Fix: Use an existing profile name (worker or debug), or add the missing profile to a service.

Step-by-step diagnosis

1. List defined profiles

• Look at services.<name>.profiles in your YAML.
• Confirm exact spelling and case.

1. Render merged config

docker compose config > .compose.resolved.yml
awk '/services:/,0 {print}' .compose.resolved.yml | sed -n '/profiles:/p'

This shows which services actually carry profiles after variable substitution and file merges.

1. Check CLI vs env selection

• CLI: --profile may be repeated: --profile dev --profile e2e
• Env: COMPOSE_PROFILES=dev,e2e (comma-separated, no spaces)
• Precedence: CLI profiles are combined with COMPOSE_PROFILES.

1. Validate YAML types and placement

• profiles must be a sequence (list). Prefer profiles: ["dev", "e2e"].
• Do not place profiles at the top level of the file.

1. Confirm all files are included

• If using multiple files, pass each with -f in order. Missing a file can drop services and their profiles.

1. Re-run with debug output (optional)

COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 docker compose --log-level DEBUG --profile dev config

Scan logs for loaded files and resulting services.

Common causes and fixes

Using profiles correctly

• Attach profiles only to services you want to be optional (e.g., debug tools, workers, e2e). Services without profiles are included by default.
• Enable multiple profiles with repeated --profile flags or via COMPOSE_PROFILES=comma,list.
• Be explicit with list syntax: profiles: ["dev", "e2e"]. Avoid a single string.
• When splitting files, keep related services and profiles together, or ensure all files are loaded with -f.
• With depends_on across profiles, ensure dependencies are also selected or remove the dependency’s profile if it must always run.
• There is no special "default" profile. The default is simply “no profiles assigned”.

Performance notes

• Faster startup: Profiles let you avoid building/pulling/starting services you don’t need (e.g., omit heavy DB or UI in CI).
• Smaller resource footprint: Less memory/CPU consumed when optional services are not selected.
• Targeted builds: docker compose --profile test build limits builds to services included by active profiles.
• Clearer environments: Create profiles per use-case (dev, e2e, debug, perf) to keep stacks lean and reproducible.

Pitfalls to avoid

• Typos and case mismatches in profile names (case-sensitive).
• Relying solely on profile names defined in comments or docs—trust the rendered config.
• Forgetting to pass all -f files; missing files can remove services and profiles silently.
• Expecting profiles to change environment variables; profiles only gate service inclusion, not per-service config.
• Mixing docker-compose (v1) and docker compose (v2) behaviors on older hosts; ensure a modern version.

Example: fixing a mismatch

compose.yml:

services:
  api:
    image: ghcr.io/example/api:latest
    profiles: ["development"]

Commands:

# Wrong: profile name doesn't exist
docker compose --profile dev up
# Right: use the defined name
docker compose --profile development up -d

Tiny FAQ

• Q: How do I list all profiles? A: There’s no dedicated command. Inspect docker compose config output for services’ profiles.

• Q: Can I exclude default services? A: Only by assigning them to a profile, then enabling only the profiles you want.

• Q: How do multiple profiles combine? A: The active set is the union of COMPOSE_PROFILES plus all --profile flags.

• Q: Do profiles affect networks/volumes? A: Indirectly. Networks/volumes used only by excluded services won’t be created.

• Q: Can I select services by name instead of profiles? A: Yes (e.g., docker compose up svc1 svc2), but profiles are better for environment-wide selection.

• Q: Are profile names restricted? A: Use simple, case-sensitive strings without spaces; hyphens and underscores are fine.