Compose Clinic
Guides / Environment · 01

Environment · 01

Your .env is read. Why is the variable missing from the service?

A resolved image tag proves that Compose read .env. It does not prove that every value became a service environment variable.

Model checkedCompose 5.3.012 Sep 20265 min

The fix

Map the value under environment, or deliberately load a service environment file with env_file. Merely placing a key in .env does not add that key to the service model.

Start by checking the resolved configuration. You can diagnose this before creating or restarting a container. Use a scratch directory and the harmless fixture values below.

Reproduce the missing entry

Create these two files in the same directory.

# .env
CC_IMAGE_TAG=1.37
CC_ONLY=not-automatically-injected
# compose.yaml
services:
  probe:
    image: busybox:${CC_IMAGE_TAG}
docker compose config --format json

Our result on Compose 5.3.0: services.probe.image is busybox:1.37, while services.probe.environment is absent. One value was used to construct the model; the other was never assigned to the service.

This checks what Compose resolves. It does not inspect variables inherited from an image or a running container.

Pass the value explicitly

services:
  probe:
    image: busybox:${CC_IMAGE_TAG}
    environment:
      CC_ONLY: ${CC_ONLY:?CC_ONLY must be set}

Run the same config command. The resolved model now includes:

environment:
  CC_ONLY: not-automatically-injected

The required-value expression prevents an empty or unset input from silently becoming a working-looking configuration. Our separate empty-value fixture exits with an error containing CC_EMPTY must be set.

If you want a file to define several service variables, create a dedicated file and point env_file at it. Keep the scope intentional: a file used for image tags and project options may contain values your application does not need.

Check the layer that is actually failing

  1. The image tag is unresolved: first check the interpolation input and file location.
  2. The model lacks your variable: add the service assignment and inspect the model again.
  3. The model is right but the application differs: check the deployed container, image defaults and application configuration. A model-only check cannot prove the runtime state.

No up, restart, image download or daemon operation was used in our proof. Before applying the change to an existing stack, review the diff and follow that stack’s release process. Reverting this fix means restoring the previous environment mapping.

config can reveal resolved secrets in a real project. Keep its output private; the downloadable proof uses only invented demonstration values.

Sources & evidence

Documentation checked 12 Sep 2026. Our fixture evidence:

Continue the investigation