How to fix ERROR: Invalid interpolation format in Docker

What this error means

The "Invalid interpolation format" error indicates that Docker Compose encountered a dollar sign ($) in your configuration file that it tried to interpret as a variable but couldn't parse correctly. Docker Compose uses Bash-like syntax for variable interpolation, supporting both `$VARIABLE` and `${VARIABLE}` formats. When Compose sees a `$` character, it attempts to process the following characters as a variable name. If the characters don't form a valid variable definition (alphanumeric names matching `[_a-zA-Z][_a-zA-Z0-9]*` or a braced expression starting with `${`), Compose throws this error. Common scenarios that trigger this error include: 1. Passwords or strings containing literal `$` characters (e.g., `MyP@ss$word`) 2. Regular expressions with `$` (e.g., `^/(sys|proc)($|/)`) 3. Shell command syntax with special variables (e.g., `$(...)` or `$@`) 4. A trailing `$` at the end of a string 5. Unsupported shell-style variable expansions like `${VAR/foo/bar}` This error is evaluated at parse time, so even commands like `docker-compose config` or `docker-compose build` will fail before any containers are created.

Typical symptoms

• Running `docker-compose up` fails immediately with 'Invalid interpolation format' error
• The error message shows the specific service and option where the problem was found
• Error occurs in environment variables containing special characters like $
• `docker-compose config` fails while trying to validate the configuration
• CI/CD pipeline fails at docker-compose parsing step
• Commands with regex patterns or shell syntax in docker-compose.yml fail
• Passwords or API keys with dollar signs cause the error

Common causes

1. Unescaped dollar sign ($) in environment variable values (most common)
2. Password or secret containing $ character not properly escaped
3. Regular expression pattern containing $ for end-of-line matching
4. Shell command syntax like $(...) or $@ in command or entrypoint
5. Trailing $ at the end of a string value
6. Using unsupported variable expansion syntax like ${VAR/foo/bar}
7. Using mandatory variable syntax ${VAR:?err} in older Compose versions
8. Dollar sign in .env file values (Compose 2.7+ expands these too)

How to fix "ERROR: Invalid interpolation format"

# WRONG - Compose tries to interpolate $word as a variable
services:
  db:
    environment:
      - DB_PASSWORD=MyP@ss$word

# CORRECT - $$ produces a literal $
services:
  db:
    environment:
      - DB_PASSWORD=MyP@ss$$word

# Command with regex
services:
  node-exporter:
    command:
      # WRONG
      - '--path.sysfs=/host/sys'
      - '--collector.filesystem.ignored-mount-points=^/(sys|proc|dev|host|etc)($$|/)'
      # CORRECT - escape the $ in regex
      - '--collector.filesystem.ignored-mount-points=^/(sys|proc|dev|host|etc)($$|/)'

# .env
DB_PASSWORD=MyP@ss$$word

# .env - single quotes prevent interpolation
DB_PASSWORD='MyP@ss$word'

# docker-compose.yml
services:
  db:
    env_file:
      - ./secrets.env  # This file's contents go directly to container

# secrets.env - not processed by Compose interpolation
DB_PASSWORD=MyP@ss$word

ERROR: Invalid interpolation format for "environment" option
in service "web": "DATABASE_URL=postgres://user:pass$word@host/db"

# Find lines containing dollar signs
grep '\$' docker-compose.yml

# Check your .env file too
grep '\$' .env

# docker-compose.yml
services:
  db:
    environment:
      # Reference shell environment variable (no value assignment)
      - DB_PASSWORD

# Set in shell (no escaping needed)
export DB_PASSWORD='MyP@ss$word'

# Run docker-compose
docker-compose up

services:
  app:
    command: >
      sh -c 'for i in $$(seq 1 5); do echo $$i; done'

#!/bin/sh
# scripts/entrypoint.sh
for i in $(seq 1 5); do
  echo $i
done

COPY scripts/entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
CMD ["/entrypoint.sh"]

services:
  app:
    build: .
    # No command needed - uses CMD from Dockerfile

# Basic substitution
image: ${REGISTRY}/myapp

# Default value if unset
image: ${REGISTRY:-docker.io}/myapp

# Default value if unset or empty
image: ${REGISTRY-docker.io}/myapp

# Error if unset (Compose v2+)
image: ${REGISTRY:?Registry must be set}

# Pattern substitution - will cause error
command: ${PATH/foo/bar}

# Substring extraction - will cause error
value: ${VAR:0:5}

# Array syntax - will cause error
args: ${@}

# Validate and show resolved configuration
docker-compose config

# If successful, you'll see the resolved YAML
# with all variables interpolated

# Show config and filter for your service
docker-compose config | grep -A 10 "db:"

db:
  environment:
    DB_PASSWORD: MyP@ss$word  # Single $ in output

Advanced notes

docker compose version  # V2
docker-compose --version  # V1 or V2 with compatibility

environment:
  # WRONG: $ will be interpolated
  - CRON_SCHEDULE=0 0 * * $
  # CORRECT
  - CRON_SCHEDULE=0 0 * * $$

command: psql -c "SELECT * FROM users WHERE name LIKE 'test$$%'"

# Match end of line
command: grep 'pattern$$' /file

# Match literal $
command: grep 'price: \$$[0-9]+' /file

# Both of these are still interpolated by Compose:
value: '$VAR'
value: "$VAR"

# Only $$ prevents interpolation:
value: '$$VAR'  # Literal $VAR

Frequently asked questions

What does "ERROR: Invalid interpolation format" mean?

The "Invalid interpolation format" error indicates that Docker Compose encountered a dollar sign ($) in your configuration file that it tried to interpret as a variable but couldn't parse correctly. Docker Compose uses Bash-like syntax for variable interpolation, supporting both $VARIABLE and ${VARIABLE} formats. When Compose sees a $ character, it attempts to process the following characters as a variable name.

How do I fix "ERROR: Invalid interpolation format"?

The 'Invalid interpolation format' error in Docker Compose occurs when the variable interpolation syntax is malformed, typically due to unescaped dollar signs ($) in your values. Fix this by escaping dollar signs with $$ or correcting the variable syntax.

What causes "ERROR: Invalid interpolation format"?

Unescaped dollar sign ($) in environment variable values (most common) Password or secret containing $ character not properly escaped Regular expression pattern containing $ for end-of-line matching

Is the "ERROR: Invalid interpolation format" error serious?

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

Related errors

• ERROR: services.web Additional property invalid is not allowed

  How to fix 'Additional property invalid is not allowed' in Docker Compose

  LOW

• yaml: line X: mapping values are not allowed in this context

  How to fix 'mapping values are not allowed in this context' in Docker Compose

  MEDIUM

• services.myservice Additional property X is not allowed

  How to fix 'Additional property is not allowed' in Docker Compose

  LOW

• dependency condition 'service_healthy' was never satisfied

  How to fix 'dependency condition service_healthy was never satisfied' in Docker Compose

  MEDIUM

• 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
• 📖
  Interpolation - Docker Compose Reference(Official Docs)
• 📖
  Set environment variables - Docker Docs(Official Docs)
• 💬
  How can I escape a $ dollar sign in a docker compose file - Stack Overflow(Stack Overflow)
• 💬
  Docker compose: Invalid interpolation format for environment option - Stack Overflow(Stack Overflow)
• 🐙
  Invalid interpolation format in command option - GitHub Issue #4485(GitHub)
• 🐙
  $ at end of environment variable causes Invalid Interpolation - GitHub Issue #2507(GitHub)