Docker Compose: 'required variable DB_PASSWORD is missing a value'

required variable DB_PASSWORD is missing a value: set DB_PASSWORD — the Compose file uses ${DB_PASSWORD:?set DB_PASSWORD}, and Compose found no value for that variable in the shell or in an .env file. Give it a value and run the command again.

Put DB_PASSWORD=... in a file named .env next to compose.yaml, or set the variable in the shell before docker compose up. The text after :? in the file is your own message, and Compose prints it at the end of the line.

The error

PS> docker compose -p fix10-cs-p1 config
error while interpolating services.db.environment.DB_PASSWORD: required variable DB_PASSWORD is missing a value: set DB_PASSWORD

docker compose -p fix10-cs-p1 up printed the same line, exited with code 1 and created nothing. The file:

services:
  db:
    image: alpine
    command: ["sh", "-c", "echo password length is $${#DB_PASSWORD}"]
    environment:
      DB_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}

Why it happens

${NAME:?message} marks a variable as required. With the variable unset, Compose stopped with the error above and created nothing. The first part of the message, services.db.environment.DB_PASSWORD, is the path in the file where the substitution sits; the part after the last colon is the text written after :?.

An empty value counts as missing. An .env file holding only DB_PASSWORD= gave the same line at config and at up, and ps -a afterwards listed no container:

PS> docker compose -p fix10-cs-pm up
error while interpolating services.db.environment.DB_PASSWORD: required variable DB_PASSWORD is missing a value: set DB_PASSWORD

The fix

An .env file in the same folder as compose.yaml:

DB_PASSWORD=not-a-real-password-123

PS> docker compose -p fix10-cs-p1 up
...
Attaching to db-1
 Container fix10-cs-p1-db-1 Starting
db-1  | password length is 23
 Container fix10-cs-p1-db-1 Started
...

Compose read the .env file on its own; the service printed the length of the value, 23 characters, so the value reached the container. Setting the variable in the shell worked as well, with no .env file:

PS> $env:DB_PASSWORD = "another-test-value"
PS> docker compose -p fix10-cs-p1 up
...
db-1  | password length is 18
...

Keep the .env file out of Git when it holds a real secret. Leave the :? in place: with an empty value it stopped up before any container was created.

How it was reproduced

One alpine service whose environment used ${DB_PASSWORD:?set DB_PASSWORD}, checked with docker compose config and started with docker compose up from Windows PowerShell 5.1, first with the variable unset, then with an .env file holding DB_PASSWORD=, then with a value from an .env file and from the shell. Docker Compose v5.7.0, Docker Engine 29.9.3, Docker Desktop 4.99.0 on Windows (version 10.0.26300). The project names fix10-cs-p1 and fix10-cs-pm and the password values are this test's own; the started project was removed with docker compose down -v.

Frequently asked

What does 'required variable is missing a value' mean in Docker Compose?

The Compose file uses the ${NAME:?message} form and the variable has no value in the shell or in the .env file. Compose stops before creating anything and prints your message at the end of the line.

How do I set a required variable for docker compose?

Write NAME=value in a file called .env next to compose.yaml, or set the variable in the shell before running docker compose. Both worked in this test.

Does an empty variable satisfy ${VAR:?} in Docker Compose?

No. In this test an .env file with DB_PASSWORD= and nothing after the equals sign produced the same 'missing a value' error as an unset variable.

More decoded errors in the Fixes category. For the plain ${VAR} form, see Docker Compose: variable is not set, defaulting to a blank string.