How to fix config "myconfig" is not defined in Docker

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 134 views

This error occurs when a Docker Compose service references a config in the `configs` section that hasn't been defined at the top-level `configs` key or doesn't exist as an external Docker config. You need to either define the config in your compose file or create it externally with Docker Swarm.

Quick fix

Fixes config "myconfig" is not defined

services:
  app:
    image: myapp
    configs:
      - myconfig  # References undefined config
  1. Add the config definition to the top-level configs section
  2. Verify config name matches exactly
  3. For external configs, initialize Swarm and create the config
  4. Use file-based configs for standalone Docker Compose
docker — error
services:
  app:
    image: myapp
    configs:
      - myconfig  # References undefined config
config "myconfig" is not defined

What this error means

Docker Compose configs allow you to inject configuration files into containers without baking them into the image. When you reference a config in a service's `configs` section, Docker expects that config to be defined either: 1. In the top-level `configs` section of your docker-compose.yml file 2. As an external config created via `docker config create` (requires Swarm mode) The error 'config "myconfig" is not defined' means the service is trying to use a config named 'myconfig', but Docker can't find its definition anywhere. This is a validation error that occurs before any containers start. Note: The `configs` feature was originally designed for Docker Swarm and has limited support in standalone Docker Compose. In older versions of docker-compose (v1), configs were completely ignored outside of Swarm mode.

Typical symptoms

  • Docker Compose fails with 'config "configname" is not defined'
  • Error occurs immediately when running docker-compose up or docker stack deploy
  • Compose file validation fails before any containers start
  • Works in one environment but fails in another (Swarm vs standalone)
  • Service starts but config file is missing inside the container

Common causes

  1. Missing top-level configs definition - service references a config not defined at the compose file's top level
  2. Typo in config name - the name in the service doesn't match the top-level definition
  3. External config not created - config marked as external but `docker config create` was never run
  4. Not in Swarm mode - external configs require Docker Swarm, but node is not a swarm manager
  5. Docker Compose v1 limitation - older docker-compose ignores configs entirely outside Swarm
  6. Case sensitivity - config names are case-sensitive and must match exactly

How to fix "config "myconfig" is not defined"

1Add the config definition to the top-level configs section

The most common fix is to define the config at the top level of your docker-compose.yml. The service references a config name, and that name must be defined in the configs section:

Before (broken):

yaml
services:
  app:
    image: myapp
    configs:
      - myconfig  # References undefined config

After (fixed):

yaml
services:
  app:
    image: myapp
    configs:
      - myconfig

configs:
  myconfig:
    file: ./config/app.conf  # Path to local config file

The file attribute tells Docker Compose where to find the config content on your host machine.

2Verify config name matches exactly

Check that the config name in your service matches the top-level definition exactly, including case:

yaml
services:
  web:
    configs:
      - source: nginx_config  # Must match exactly
        target: /etc/nginx/nginx.conf

configs:
  nginx_config:  # This name must match the source above
    file: ./nginx.conf

Common mistakes:
- nginx-config vs nginx_config (hyphens vs underscores)
- NginxConfig vs nginxconfig (case differences)
- Extra whitespace in YAML

3For external configs, initialize Swarm and create the config

If you're using external: true, you must be in Swarm mode and create the config first:

bash
# Initialize swarm mode (if not already done)
docker swarm init

# Create the config from a file
docker config create myconfig ./path/to/config.file

# Verify it was created
docker config ls

Then in your compose file:

yaml
configs:
  myconfig:
    external: true

Now docker stack deploy will find the external config.

4Use file-based configs for standalone Docker Compose

If you're running docker compose up (not docker stack deploy), avoid external configs and use file-based configs instead:

yaml
configs:
  app_config:
    file: ./configs/application.yml

services:
  app:
    image: myapp
    configs:
      - source: app_config
        target: /app/config.yml
        mode: 0440

This approach works without Swarm mode in Docker Compose v2+.

5Upgrade to Docker Compose v2 if configs are being ignored

Older docker-compose (Python-based v1) would silently ignore the configs section outside Swarm mode. Docker Compose v2 (Go-based, docker compose without hyphen) has better support:

bash
# Check your version
docker compose version

# If you see v1.x, upgrade to v2
# On Ubuntu/Debian:
sudo apt-get update
sudo apt-get install docker-compose-plugin

# On macOS with Docker Desktop, update Docker Desktop
# Configs support was added around v2.0

After upgrading, use docker compose (with space) instead of docker-compose (with hyphen).

6Use bind mounts as an alternative to configs

If configs aren't working in your environment, bind mounts achieve similar results:

yaml
services:
  app:
    image: myapp
    volumes:
      - ./config/app.conf:/etc/app/app.conf:ro

The :ro flag makes it read-only, similar to how configs work. This approach:
- Works in all Docker versions
- Doesn't require Swarm mode
- Changes to the file on the host are immediately visible in the container

Advanced notes

Configs vs Secrets: Docker also has a secrets feature that works similarly but is designed for sensitive data. Secrets are mounted at /run/secrets/ by default and have stricter permissions. Use configs for non-sensitive configuration files.

Swarm mode configs: In Swarm mode, configs are stored in the Raft log and distributed to nodes that need them. They're immutable once created - to update a config, you must create a new one with a different name and update your service.

Config size limits: Docker configs have a size limit of 500KB. For larger configuration files, use volumes or bind mounts instead.

Compose file version: The configs top-level element requires Compose file format version 3.3 or higher. Ensure your compose file specifies an appropriate version:

yaml
version: '3.8'

Debugging config issues:

bash
# Validate compose file syntax
docker compose config

# List existing configs (Swarm mode)
docker config ls

# Inspect a config's metadata
docker config inspect myconfig

Frequently asked questions

What does "config "myconfig" is not defined" mean?
Docker Compose configs allow you to inject configuration files into containers without baking them into the image. When you reference a config in a service's configs section, Docker expects that config to be defined either: 1. yml file 2.
How do I fix "config "myconfig" is not defined"?
This error occurs when a Docker Compose service references a config in the configs section that hasn't been defined at the top-level configs key or doesn't exist as an external Docker config. You need to either define the config in your compose file or create it externally with Docker Swarm.
What causes "config "myconfig" is not defined"?
Missing top-level configs definition - service references a config not defined at the compose file's top level Typo in config name - the name in the service doesn't match the top-level definition External config not created - config marked as external but docker config create was never run
Is the "config "myconfig" is not defined" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading