How to fix environment variable has empty value in Docker

What this error means

The "environment variable has empty value" warning (or the related "variable is not set. Defaulting to a blank string" warning) indicates that Docker Compose is trying to substitute an environment variable in your docker-compose.yml file, but that variable either doesn't exist in your shell environment or has no value assigned. When you use `${VARIABLE_NAME}` syntax in a docker-compose.yml file, Docker Compose looks for that variable in: 1. Your current shell environment 2. The `.env` file in your project root 3. Values passed via `--env-file` flag If the variable isn't found in any of these locations, Docker Compose substitutes an empty string and shows this warning. While your containers may still start, the empty value could cause runtime issues depending on how the variable is used. This is different from the `env_file:` directive, which passes variables INTO containers. The warning occurs during Compose file parsing when Docker is trying to build the configuration before any containers start. Common scenarios where this occurs: - Using `${DATABASE_URL}` in docker-compose.yml without setting it - Cloning a project that expects certain environment variables to be set - CI/CD pipelines where secrets weren't properly injected - Typos in variable names (case-sensitive on Linux)

Typical symptoms

• Warning message: 'The VARIABLE_NAME variable is not set. Defaulting to a blank string.'
• Docker Compose commands show warnings but containers still start
• Application inside container fails due to missing configuration values
• Environment-dependent settings (like database URLs) resolve to empty strings
• Running `docker-compose config` shows empty values for expected variables
• CI/CD pipeline logs show environment variable warnings before deployment
• Different behavior between local development and production environments

Common causes

1. The environment variable is not exported in your shell (most common)
2. The .env file is missing, empty, or in the wrong directory
3. Variable name has a typo or case mismatch (Linux is case-sensitive)
4. Special characters like $ in the value causing unintended variable expansion
5. Using env_file directive expecting it to work for Compose file substitution (it doesn't)
6. Running docker-compose with sudo which doesn't preserve environment variables
7. The variable is set in a child process but not exported to the parent shell

How to fix "environment variable has empty value"

# The warning looks like this:
# WARN[0000] The "DATABASE_URL" variable is not set. Defaulting to a blank string.

# Check if the variable exists in your environment
echo $DATABASE_URL

# Or check all environment variables
env | grep DATABASE_URL

# View what Docker Compose sees
docker-compose config

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

# Verify it's set
echo $DATABASE_URL

# Now run docker-compose
docker-compose up

# For bash (add to ~/.bashrc or ~/.bash_profile)
echo 'export DATABASE_URL="postgres://user:pass@localhost:5432/mydb"' >> ~/.bashrc
source ~/.bashrc

# For zsh (add to ~/.zshrc)
echo 'export DATABASE_URL="postgres://user:pass@localhost:5432/mydb"' >> ~/.zshrc
source ~/.zshrc

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

# Show the resolved configuration
docker-compose config

# Or specify a different env file
docker-compose --env-file ./config/.env up

services:
  app:
    image: myapp
    environment:
      # Use :- for default when unset or empty
      - DATABASE_URL=${DATABASE_URL:-postgres://localhost:5432/dev}

      # Use - for default only when unset (allows empty values)
      - OPTIONAL_VAR=${OPTIONAL_VAR-default_value}

      # Require the variable (fail if not set)
      - REQUIRED_VAR=${REQUIRED_VAR:?Error: REQUIRED_VAR must be set}

# Problem: $ in password gets interpreted
PASSWORD="p@ss$word123"  # $word gets expanded to empty string

# In .env file (values aren't typically quoted, but this varies)
PASSWORD=p@ss$word123

# Or if your version supports it:
PASSWORD='p@ss$word123'

services:
  app:
    environment:
      # Use $$ to escape a literal $ sign
      - PASSWORD=p@ss$$word123

export PASSWORD='p@ss$word123'

# This loses your environment variables
sudo docker-compose up  # Variables not available!

# Option 1: Use -E to preserve environment
sudo -E docker-compose up

# Option 2: Pass variables explicitly
sudo DATABASE_URL="$DATABASE_URL" docker-compose up

# Option 3: Add yourself to docker group (recommended)
sudo usermod -aG docker $USER
# Log out and back in, then:
docker-compose up  # No sudo needed!

# Show the fully resolved configuration
docker-compose config

# Check which variables are resolved
docker-compose config | grep -A5 environment

# Verbose output for debugging (Compose V2)
docker compose config --environment

Advanced notes

services:
  db:
    # Substitution: TAG comes from shell/.env
    image: postgres:${POSTGRES_TAG:-15}

    # Container environment: these go inside the container
    environment:
      - POSTGRES_PASSWORD=${DB_PASSWORD:-secret}

    # env_file: loads vars into container, NOT for substitution
    env_file:
      - ./db.env

# GitHub Actions example
jobs:
  deploy:
    steps:
      - name: Set up environment
        run: |
          echo "DATABASE_URL=${{ secrets.DATABASE_URL }}" >> .env
          echo "API_KEY=${{ secrets.API_KEY }}" >> .env

      - name: Deploy
        run: docker-compose up -d

steps:
      - name: Deploy
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          API_KEY: ${{ secrets.API_KEY }}
        run: docker-compose up -d

services:
  app:
    environment:
      # Provide empty default to silence warning
      - OPTIONAL_FEATURE=${OPTIONAL_FEATURE:-}

      # Or use a meaningful default
      - LOG_LEVEL=${LOG_LEVEL:-info}

# Shell (double quotes expand variables)
echo "Value: $HOME"         # Expands $HOME
echo 'Value: $HOME'         # Literal $HOME

# .env file (usually no quotes, no expansion)
HOME_DIR=/home/user         # Literal value

# docker-compose.yml (uses Compose substitution)
image: myapp:${TAG}         # Uses Compose's substitution
command: echo $$HOME        # $$ escapes to literal $ for container

docker compose config --environment

docker compose --verbose up 2>&1 | head -20

# What's in your shell?
   echo $MY_VAR

   # What does Compose resolve?
   docker compose config | grep MY_VAR

Frequently asked questions

What does "environment variable has empty value" mean?

The "environment variable has empty value" warning (or the related "variable is not set. yml file, but that variable either doesn't exist in your shell environment or has no value assigned. yml file, Docker Compose looks for that variable in: 1.

How do I fix "environment variable has empty value"?

The 'environment variable has empty value' warning in Docker or Docker Compose appears when a referenced environment variable is not set or defaults to a blank string. This is typically resolved by setting the variable in your shell, using a .env file, or providing a default value in your configuration.

What causes "environment variable has empty value"?

The environment variable is not exported in your shell (most common) The .env file is missing, empty, or in the wrong directory Variable name has a typo or case mismatch (Linux is case-sensitive)

Is the "environment variable has empty value" error serious?

It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• Error starting daemon: error initializing graphdriver: driver not supported

  How to fix 'error initializing graphdriver: driver not supported' in Docker

  HIGH

• exec user process caused: permission denied

  How to fix 'exec user process caused: permission denied' in Docker

  MEDIUM

• Error processing tar file(exit status 1): unexpected EOF

  How to fix 'Error processing tar file: unexpected EOF' in Docker

  MEDIUM

• docker: Error response from daemon: OCI runtime create failed: container_linux.go: starting container process caused: exec: "/docker-entrypoint.sh": stat /docker-entrypoint.sh: no such file or directory

  How to fix 'exec: entrypoint.sh: no such file or directory' in Docker

  HIGH

• WSL 2 requires an update to its kernel component

  How to fix 'WSL 2 requires an update to its kernel component' in Docker

  MEDIUM

• dial tcp: i/o timeout

  How to fix 'dial tcp: i/o timeout' in Docker

  MEDIUM

Official resources & further reading

• 📚Docker Official Documentation
• 💬
  Docker-Compose Environment-Variables blank string - Stack Overflow(Stack Overflow)
• 💬
  Environment variables in docker-compose are substituted as empty string - Stack Overflow(Stack Overflow)
• 💬
  Docker-compose environment variable is not set - Stack Overflow(Stack Overflow)
• 🐙
  Not possible to set environment variable to empty string - GitHub Issue(GitHub)
• 🐙
  Env variable defaulting to blank string - GitHub Issue(GitHub)
• 📖
  Variable Interpolation - Docker Docs(Official Docs)
• 📖
  Set environment variables - Docker Docs(Official Docs)
• 📝
  100 Common Docker Errors & Solutions - DEV Community