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.
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.
Open the file referenced in extends.file and confirm the service exists with the exact name:
# 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# 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.
The file path in extends is relative to the location of the Compose file containing the extends directive:
# Check if the file exists
ls -la common-services.yml
# If in a subdirectory
ls -la ./config/common-services.ymlservices:
webapp:
extends:
file: ./config/common-services.yml # Path relative to this file
service: base-appIf you omit the file key, Docker Compose looks for the service in the same file:
services:
base-app:
image: node:18
webapp:
extends:
service: base-app # Extends from same file (no file key needed)
ports:
- "3000:3000"Use docker-compose config to check if your configuration is valid:
# Validate and show merged configuration
docker-compose config
# If using a custom file
docker-compose -f docker-compose.yml configThis will either show the merged configuration or display the exact error with line numbers, helping you pinpoint the issue.
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:
# 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
- databaseThe extends feature has had varying support across versions:
# Check your Docker Compose version
docker compose version
# or
docker-compose --versionVersion 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:
# 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:
...If extends continues to cause issues, YAML anchors provide similar functionality:
# 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 workerYAML anchors work within a single file and don't have the same limitations as extends.
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:
# This will fail - circular reference
services:
a:
extends:
service: b
b:
extends:
service: aPath 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.
dockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
Error response from daemon: manifest for nginx:nonexistent not found: manifest unknown: manifest unknown
How to fix 'manifest for image:tag not found' in Docker
Error response from daemon: invalid reference format: repository name must be lowercase
How to fix 'repository name must be lowercase' in Docker
Error response from daemon: No such image
How to fix 'No such image' in Docker
Error response from daemon: Container is not running
How to fix 'Container is not running' when using docker exec