Docker Compose Profile Service Not Starting: Check depends_on and Activation

Understand what a profile changes#

Profiles apply to services. A service without profiles is always enabled; a profiled service is ignored unless an active profile matches or you explicitly target that service. Other top-level Compose elements are not switched off by profiles.

This small file has two independent optional groups:

1
services:
2
  web:
3
    image: nginx:alpine
4

5
  db:
6
    image: postgres
7
    environment:
8
      POSTGRES_PASSWORD: example
9

10
  adminer:
11
    image: adminer
12
    profiles: [debug]
13
    depends_on:
14
      - db
15

16
  test-runner:
17
    image: alpine
18
    profiles: [test]
19
    command: ['sh', '-c', 'echo tests']
20

21
  coverage:
22
    image: alpine
23
    profiles: [test]
24
    depends_on:
25
      - test-runner
26
    command: ['sh', '-c', 'echo coverage']

docker compose --profile debug up includes web, db, and adminer. docker compose --profile test up includes web, db, test-runner, and coverage. A command without --profile starts only the services without a profile.

Fix a dependency in another profile#

This is the failure pattern:

1
services:
2
  debug-shell:
3
    image: alpine
4
    profiles: [debug]
5
    depends_on:
6
      - test-runner
7

8
  test-runner:
9
    image: alpine
10
    profiles: [test]

With only debug active, debug-shell is selected but test-runner is ignored. Compose cannot satisfy the dependency and reports an invalid model. Docker’s profiles reference describes this as a profile mismatch; depends_on does not magically enable a service in a different inactive profile.

Choose the fix that matches the intended lifecycle:

1. Put both services in the same profile when they are one optional feature.

2. Enable both profiles when the dependency is intentionally shared:

   1
   docker compose --profile debug --profile test up
   

3. Remove the profile from a dependency that should always exist, such as a database used by every local mode.

Do not add every profile to every service as a blanket fix. That makes optional services start unexpectedly and hides the dependency contract.

Verify the active model before starting containers#

docker compose config parses, resolves, and renders the actual model that Docker Engine will receive. Use it with the same working directory and environment file as your real command:

1
# Baseline: services without a profile.
2
docker compose config --services
3

4
# Debug model: profile services now included.
5
docker compose --profile debug config --services
6

7
# Validate the dependency graph without printing the full YAML.
8
docker compose --profile debug config --quiet
9

10
# See the profile names declared by this project.
11
docker compose config --profiles

If debug-shell appears in config --services but test-runner does not, the profile set is wrong. If config --quiet fails, fix the model before pulling images or debugging container logs.

The config command also resolves interpolation and paths. This makes it useful for CI, where COMPOSE_PROFILES, --env-file, and the working directory can differ from a local shell.

Activate profiles consistently in CI#

Use one activation contract for local commands and automation. Docker supports repeated --profile flags and the COMPOSE_PROFILES environment variable:

1
COMPOSE_PROFILES=debug,test docker compose config --quiet
2
COMPOSE_PROFILES=debug,test docker compose up -d

If a command-line --profile is present, it takes precedence over the related environment setting. Put the profile selection next to the command that needs it instead of relying on a developer’s persistent shell environment.

An explicit service target also activates that service’s profile:

1
docker compose run --rm coverage

That shortcut does not repair a dependency in a different profile. If the selected service depends on another profiled service, activate the shared profile or target a model where the dependency is always enabled.

Keep profiles separate from Compose file merging#

Profiles change which services are in one Compose model. They are not the same as -f overrides or include modules:

• Use profiles for optional services such as debugging, testing, or local observability.
• Use -f when a second file should override or extend a base model.
• Use include when a module should retain its own path and environment context.

Combining these features is valid, but debug them in layers: first render the merged files, then enable the profiles, then start the selected services.

FAQ#