How to fix ERROR: Missing required environment variable in Docker

DockerBEGINNERMEDIUMUpdated Dec 6, 2025· 292 views

The 'Missing required environment variable' error in Docker Compose occurs when using the `${VAR?error}` or `${VAR:?error}` syntax to require a variable that isn't set in your environment. This is resolved by setting the required variable, providing a default value, or using an .env file.

Quick fix

Fixes ERROR: Missing required environment variable

# Run docker-compose to see the error
docker-compose config

# Example output:
# ERROR: Missing required environment variable "DATABASE_URL"
# Or: required variable DATABASE_URL is missing a value: Database connection required
  1. Identify which variable is missing
  2. Set the required environment variable
  3. Create or update the .env file
  4. Provide a default value in the compose file
docker — error
# Run docker-compose to see the error
docker-compose config
# Example output:
# ERROR: Missing required environment variable "DATABASE_URL"
# Or: required variable DATABASE_URL is missing a value: Database connection required
ERROR: Missing required environment variable

What this error means

The "Missing required environment variable" error indicates that Docker Compose encountered variable interpolation syntax that explicitly requires a variable to be set, but that variable was not found in the environment. Docker Compose supports special syntax for requiring environment variables: - `${VARIABLE?error}` - Fails if VARIABLE is unset (but allows empty string) - `${VARIABLE:?error}` - Fails if VARIABLE is unset OR empty When Docker Compose parses your `docker-compose.yml` file and finds this syntax with an undefined variable, it immediately stops and displays this error. This is actually a safety feature that prevents your services from starting with missing configuration. This error commonly appears when: 1. You've cloned a project that expects certain environment variables to be set 2. The `.env` file is missing or incomplete 3. You're running Docker Compose in a CI/CD environment without proper variable configuration 4. The Compose file was written to require specific variables for security or configuration purposes Unlike variables without the `?` modifier (which silently substitute an empty string), required variables provide explicit validation that critical configuration is present before containers start.

Typical symptoms

  • Running `docker-compose up` fails immediately with 'Missing required environment variable'
  • Error message shows the specific variable name that's missing
  • `docker-compose config` fails to validate the configuration
  • Warning appears as 'required variable VARNAME is missing a value'
  • Build or pull commands fail before any container operations begin
  • Error shows 'invalid interpolation format' with a variable reference
  • CI/CD pipelines fail at docker-compose step with missing variable errors

Common causes

  1. Required variable syntax `${VAR?error}` or `${VAR:?error}` is used but variable is not set
  2. The .env file is missing from the project directory
  3. The .env file exists but doesn't contain the required variable
  4. Running docker-compose from a directory where .env is not found
  5. Environment variable is set but empty (when using :? syntax)
  6. CI/CD environment doesn't have required secrets or variables configured
  7. Docker Compose --env-file flag pointing to wrong or missing file
  8. Multiple compose files with different variable requirements

How to fix "ERROR: Missing required environment variable"

1Identify which variable is missing

First, check the error message to find which variable is required:

bash
# Run docker-compose to see the error
docker-compose config

# Example output:
# ERROR: Missing required environment variable "DATABASE_URL"
# Or: required variable DATABASE_URL is missing a value: Database connection required

The error message tells you exactly which variable needs to be set. Note the variable name for the next steps.

You can also search your compose file for required variable syntax:

bash
# Find required variables in your compose file
grep -E '\$\{[^}]+\?' docker-compose.yml
2Set the required environment variable

The most direct fix is to set the required variable. You have several options:

Option 1: Set in shell before running docker-compose

bash
# Export the variable
export DATABASE_URL="postgres://user:pass@localhost:5432/mydb"

# Then run docker-compose
docker-compose up

Option 2: Set inline with the command

bash
DATABASE_URL="postgres://user:pass@localhost:5432/mydb" docker-compose up

Option 3: Add to your shell profile (~/.bashrc, ~/.zshrc)

bash
echo 'export DATABASE_URL="postgres://user:pass@localhost:5432/mydb"' >> ~/.bashrc
source ~/.bashrc

Verify the variable is set:

bash
echo $DATABASE_URL
3Create or update the .env file

Docker Compose automatically reads a .env file from the project directory. Create or update it:

bash
# Create .env file in your project directory
cat > .env << 'EOF'
# Required environment variables
DATABASE_URL=postgres://user:pass@localhost:5432/mydb
API_KEY=your-api-key-here
REDIS_URL=redis://localhost:6379
EOF

If a .env.example file exists, use it as a template:

bash
cp .env.example .env
# Then edit .env to fill in actual values

Verify the .env file is being read:

bash
# This command shows the resolved configuration
docker-compose config

Important: The .env file must be in the same directory as your docker-compose.yml file, or specify it with --env-file:

bash
docker-compose --env-file ./config/.env up
4Provide a default value in the compose file

If the variable is optional in some environments, modify the compose file to provide a default:

Before (requires variable):

yaml
services:
  app:
    environment:
      - DATABASE_URL=${DATABASE_URL?Database URL is required}

After (with default value):

yaml
services:
  app:
    environment:
      # Use :- for default when unset or empty
      - DATABASE_URL=${DATABASE_URL:-postgres://localhost:5432/default}
      # Use - for default only when unset
      - LOG_LEVEL=${LOG_LEVEL-info}

Variable substitution syntax:
| Syntax | Behavior |
|--------|----------|
| ${VAR} | Substitutes value or empty string |
| ${VAR:-default} | Uses default if unset or empty |
| ${VAR-default} | Uses default if unset |
| ${VAR:?error} | Fails if unset or empty |
| ${VAR?error} | Fails if unset |

5Fix the variable in CI/CD environments

For CI/CD pipelines, ensure required variables are available:

GitHub Actions:

yaml
# .github/workflows/deploy.yml
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
      API_KEY: ${{ secrets.API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - name: Deploy with Docker Compose
        run: docker-compose up -d

GitLab CI:

yaml
# .gitlab-ci.yml
deploy:
  variables:
    DATABASE_URL: $DATABASE_URL  # From CI/CD settings
  script:
    - docker-compose up -d

Create .env from secrets in CI:

bash
# Create .env file from environment
cat > .env << EOF
DATABASE_URL=${DATABASE_URL}
API_KEY=${API_KEY}
EOF
docker-compose up -d
6Check for empty vs unset variables

There's a subtle difference between ${VAR?error} and ${VAR:?error}:

- `?` - Only fails if variable is completely unset
- `:?` - Fails if variable is unset OR empty

If you're getting errors with a variable you've set, check if it's empty:

bash
# Check if variable is set and show its value
echo "DATABASE_URL='$DATABASE_URL'"

# In .env file, ensure no spaces around =
# Correct:
DATABASE_URL=postgres://localhost/db

# Wrong (empty value):
DATABASE_URL=
DATABASE_URL=
DATABASE_URL=""

If the compose file uses :? and you need to allow empty values, change to ?:

yaml
# Fails if empty or unset
- DEBUG_MODE=${DEBUG_MODE:?Debug mode required}

# Only fails if unset (allows empty)
- DEBUG_MODE=${DEBUG_MODE?Debug mode required}
7Handle multiple compose files with different variables

When using multiple compose files, each may have different required variables:

bash
# Check which variables are needed in each file
grep -E '\$\{[^}]+\?' docker-compose.yml docker-compose.override.yml docker-compose.prod.yml

# Ensure all required variables are set for the files you're using
docker-compose -f docker-compose.yml -f docker-compose.prod.yml config

Create environment-specific .env files:

bash
# Development
docker-compose --env-file .env.dev up

# Production
docker-compose --env-file .env.prod -f docker-compose.yml -f docker-compose.prod.yml up

Or use profiles to conditionally include services:

yaml
services:
  app:
    # Always runs
    environment:
      - DATABASE_URL=${DATABASE_URL:?Required}

  debug-tools:
    profiles: ["debug"]
    # Only validates when profile is active
    environment:
      - DEBUG_TOKEN=${DEBUG_TOKEN:?Required for debug}

Advanced notes

### Understanding Variable Interpolation Syntax

Docker Compose uses shell-style variable interpolation with several modifiers:

| Syntax | Behavior |
|--------|----------|
| ${VAR} | Substitute value, empty string if unset |
| ${VAR:-default} | Use default if VAR is unset or empty |
| ${VAR-default} | Use default if VAR is unset |
| ${VAR:+replacement} | Use replacement if VAR is set and non-empty |
| ${VAR+replacement} | Use replacement if VAR is set |
| ${VAR:?error} | Fail with error if VAR is unset or empty |
| ${VAR?error} | Fail with error if VAR is unset |

### Known Bugs and Quirks

Bug: Required variables not throwing errors when not last (Issue #10011)

There's a known bug where required variables only throw errors when they're the last part of an interpolation:

yaml
# This throws an error if MY_VAR is unset
path: ${MY_VAR?Required}

# This may silently continue with empty string!
path: ${MY_VAR?Required}/subdir

Workaround: Put required variables last or test separately.

Required variables evaluated on unrelated services (Issue #6978)

Docker Compose validates ALL variable references when parsing, even for services you're not running:

bash
# This fails even if you're only starting 'web'
docker-compose up web

# If 'worker' service has ${WORKER_SECRET:?Required}
# and WORKER_SECRET is not set

Workaround: Use profiles to isolate services with different requirements.

### .env File vs --env-file Flag vs env_file Directive

These three mechanisms serve different purposes:

1. .env file (automatic loading)
- Auto-loaded from project directory
- Used for Compose file variable interpolation
- Example: image: ${REGISTRY}/app:${TAG}

2. --env-file flag
- Overrides the .env file location
- Still used for Compose file interpolation
- docker-compose --env-file ./config/.env up

3. env_file directive (in services)
- Passes variables TO containers at runtime
- Not used during Compose file parsing
- Different from the .env file!

yaml
services:
  app:
    env_file:
      - ./runtime.env  # These go INTO the container
    environment:
      - FROM_COMPOSE=${HOST_VAR}  # This is interpolated from .env

### Docker Compose with Bake (BuildKit)

As of Docker 28.3.0+, the BAKE feature may cause different behavior with environment variables during builds:

bash
# If seeing issues with BAKE enabled
DOCKER_BUILDKIT=0 docker-compose build

# Or set in Docker daemon config
# ~/.docker/daemon.json
{
  "features": {
    "buildkit": false
  }
}

### Security Best Practices

1. Never commit .env files with secrets

gitignore
# .gitignore
   .env
   .env.local
   .env.*.local

2. Provide .env.example as a template

bash
# .env.example (committed to repo)
   DATABASE_URL=postgres://user:pass@host:5432/db
   API_KEY=your-api-key-here

3. Use required syntax for critical variables

yaml
environment:
     - DATABASE_URL=${DATABASE_URL:?Database URL must be set}
     - JWT_SECRET=${JWT_SECRET:?JWT secret is required}

4. Use Docker secrets for production

yaml
services:
     app:
       secrets:
         - db_password
   secrets:
     db_password:
       external: true

Frequently asked questions

What does "ERROR: Missing required environment variable" mean?
The "Missing required environment variable" error indicates that Docker Compose encountered variable interpolation syntax that explicitly requires a variable to be set, but that variable was not found in the environment. yml file and finds this syntax with an undefined variable, it immediately stops and displays this error. This is actually a safety feature that prevents your services from starting with missing configuration.
How do I fix "ERROR: Missing required environment variable"?
The 'Missing required environment variable' error in Docker Compose occurs when using the ${VAR?error} or ${VAR:?error} syntax to require a variable that isn't set in your environment. This is resolved by setting the required variable, providing a default value, or using an .env file.
What causes "ERROR: Missing required environment variable"?
Required variable syntax ${VAR?error} or ${VAR:?error} is used but variable is not set The .env file is missing from the project directory The .env file exists but doesn't contain the required variable
Is the "ERROR: Missing required environment variable" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading