How to fix ERROR: Cannot find service 'base' referenced in extends in Docker

DockerBEGINNERLOWUpdated Dec 1, 2025· 112 views

This error occurs when Docker Compose cannot locate the service you're trying to extend. The extends feature allows you to share common configurations between services, but requires the base service to be properly defined and accessible in the referenced file.

Quick fix

Fixes ERROR: Cannot find service 'base' referenced in extends

# common-services.yml - the file you're extending FROM
services:
  base-app:           # <-- This name must match exactly
    image: node:18
    environment:
      - NODE_ENV=production
    working_dir: /app
  1. Verify the base service exists in the source file
  2. Check the file path is correct
  3. Validate your compose configuration
  4. Ensure the base service doesn't use unsupported features
docker — error
# common-services.yml - the file you're extending FROM
services:
  base-app:           # <-- This name must match exactly
    image: node:18
    environment:
      - NODE_ENV=production
    working_dir: /app
ERROR: Cannot find service 'base' referenced in extends

What this error means

The `extends` keyword in Docker Compose allows you to share common service configurations between different services or even different Compose files. When you see "Cannot find service referenced in extends," it means Docker Compose looked for the base service you specified but couldn't locate it. This inheritance mechanism works by specifying a `file` (optional, defaults to current file) and `service` name to inherit from: ```yaml services: webapp: extends: file: common-services.yml service: base-app # <-- This service must exist! ``` The error occurs when `base-app` doesn't exist in `common-services.yml`, or when the file path is incorrect. Docker Compose needs to find the exact service definition to merge its configuration with your extending service. Note that the base service itself is NOT automatically included in your project - you're only inheriting its configuration properties. The service must exist in the referenced file but won't be started unless you also define it in your main Compose file.

Typical symptoms

  • Running 'docker-compose up' fails with 'Cannot find service' error referencing extends
  • Error message specifically mentions the service name and 'extends' keyword
  • docker-compose config fails to validate the compose file
  • The error appears when trying to use configuration inheritance between services
  • Working setup breaks after renaming services or moving files

Common causes

  1. The service name in extends.service doesn't match any service in the referenced file
  2. The file path in extends.file is incorrect or the file doesn't exist
  3. Typo in the service name (names are case-sensitive)
  4. The base service was renamed or removed from the source file
  5. Using relative paths that resolve differently from the current working directory
  6. Trying to extend a service that uses 'include' directive (not supported in some versions)
  7. The base service has depends_on, links, or volumes_from which prevent extending
  8. Docker Compose version incompatibility with extends feature

How to fix "ERROR: Cannot find service 'base' referenced in extends"

1Verify the base service exists in the source file

Open the file referenced in extends.file and confirm the service exists with the exact name:

yaml
# common-services.yml - the file you're extending FROM
services:
  base-app:           # <-- This name must match exactly
    image: node:18
    environment:
      - NODE_ENV=production
    working_dir: /app
yaml
# docker-compose.yml - your main compose file
services:
  webapp:
    extends:
      file: common-services.yml
      service: base-app  # Must match exactly, case-sensitive
    ports:
      - "3000:3000"

Check for typos - service names are case-sensitive.

2Check the file path is correct

The file path in extends is relative to the location of the Compose file containing the extends directive:

bash
# Check if the file exists
ls -la common-services.yml

# If in a subdirectory
ls -la ./config/common-services.yml
yaml
services:
  webapp:
    extends:
      file: ./config/common-services.yml  # Path relative to this file
      service: base-app

If you omit the file key, Docker Compose looks for the service in the same file:

yaml
services:
  base-app:
    image: node:18

  webapp:
    extends:
      service: base-app  # Extends from same file (no file key needed)
    ports:
      - "3000:3000"
3Validate your compose configuration

Use docker-compose config to check if your configuration is valid:

bash
# Validate and show merged configuration
docker-compose config

# If using a custom file
docker-compose -f docker-compose.yml config

This will either show the merged configuration or display the exact error with line numbers, helping you pinpoint the issue.

4Ensure the base service doesn't use unsupported features

Services with certain directives cannot be extended. Docker Compose explicitly prevents extending services that use:

- depends_on
- links
- volumes_from

If your base service has these, remove them or restructure:

yaml
# This will cause "can't be used with extends" error
services:
  base:
    image: node:18
    depends_on:        # <-- Remove this from base service
      - database

# Instead, add depends_on in the extending service
services:
  webapp:
    extends:
      service: base
    depends_on:        # <-- Add it here instead
      - database
5Check Docker Compose version compatibility

The extends feature has had varying support across versions:

bash
# Check your Docker Compose version
docker compose version
# or
docker-compose --version

Version history:
- Compose v2.1 and earlier: Full extends support
- Compose v3.0-3.7: extends was removed
- Compose v1.27+: extends support restored for v3

If you're using an older v3 file, consider:

yaml
# Change version or remove it entirely (recommended for modern Docker)
# Old way (may not support extends):
version: "3.7"

# New way (supports extends):
# Just remove the version line entirely
services:
  ...
6Use YAML anchors as an alternative

If extends continues to cause issues, YAML anchors provide similar functionality:

yaml
# Define a reusable configuration block
x-common: &common-config
  image: node:18
  environment:
    - NODE_ENV=production
  working_dir: /app

services:
  webapp:
    <<: *common-config  # Merge the common config
    ports:
      - "3000:3000"
    command: npm start

  worker:
    <<: *common-config
    command: npm run worker

YAML anchors work within a single file and don't have the same limitations as extends.

Advanced notes

Extends vs Include vs Merge: Docker Compose offers multiple ways to share configurations:

- extends: Inherits configuration from a specific service (service-level inheritance)
- include: Imports entire Compose files as subprojects (file-level import, Compose v2.20+)
- merge (-f flags): Combines multiple Compose files sequentially

extends is best for sharing service templates, while include is better for modular project organization.

Extends with include limitation: As of Docker Compose v2.24, you cannot extend a service that's defined via the include directive. The extends resolver runs before include resolution, so the service isn't visible yet. Workaround: define the base service in a separate file and reference it directly.

Known issues in specific versions:
- v2.24.6 introduced stricter validation for depends_on in extended services
- Downgrading to v2.24.5 may resolve some edge cases
- v2.3.0-2.3.2 had bugs with complex multi-file setups

Circular references: Docker Compose detects and prevents circular extends references:

yaml
# This will fail - circular reference
services:
  a:
    extends:
      service: b
  b:
    extends:
      service: a

Path resolution: When extending from another file, relative paths in the base service (like build context or volume mounts) are automatically converted to remain valid from the extending service's perspective.

Frequently asked questions

What does "ERROR: Cannot find service 'base' referenced in extends" mean?
The extends keyword in Docker Compose allows you to share common service configurations between different services or even different Compose files. When you see "Cannot find service referenced in extends," it means Docker Compose looked for the base service you specified but couldn't locate it. yml, or when the file path is incorrect.
How do I fix "ERROR: Cannot find service 'base' referenced in extends"?
This error occurs when Docker Compose cannot locate the service you're trying to extend. The extends feature allows you to share common configurations between services, but requires the base service to be properly defined and accessible in the referenced file.
What causes "ERROR: Cannot find service 'base' referenced in extends"?
The service name in extends.service doesn't match any service in the referenced file The file path in extends.file is incorrect or the file doesn't exist Typo in the service name (names are case-sensitive)
Is the "ERROR: Cannot find service 'base' referenced in extends" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading