Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Docker Compose says a service property contains an invalid type

ErrorThe PORT variable is not set. Defaulting to a blank string.

Short answer

Compose reports an invalid type when a value does not have the shape the file format expects. The usual trigger is a variable such as ${PORT} that is unset, so Compose substitutes an empty string. Run docker compose config to see the resolved file, set the variable, and quote HOST:CONTAINER port strings.

  • Applies to Docker Compose v2, Docker Engine 27
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the file after variable substitution. The broken value shows up in the output, usually empty.

    docker compose config
  2. 2Match what you see, then jump to its fix

    1. 1A warning that a variable is not set, just before the invalid type errorA variable in the ports entry is unset or in another folderFix
    2. 2The ports value looks like 22:22 or a number-like pair without quotesA port mapping is not written as a quoted stringFix
    3. 3The error names environment, command or healthcheck instead of portsenvironment or command uses the wrong shapeFix

What does the error look like?

  • The PORT variable is not set. Defaulting to a blank string.
  • The Compose file './docker-compose.yaml' is invalid because:
  • services.foo.ports contains an invalid type, it should be a number, or an object

Cause 1 of 3

A variable in the ports entry is unset or in another folder

1Check

An unset variable becomes an empty string. Compose reads .env from the project directory, not from wherever you happen to be, and --env-file replaces it.

docker compose config --environment
ls -a .env

2Fix

Define the variable in the .env next to the compose file, pass the right file with --env-file, or give the variable a default or a hard requirement in the compose file.

ports:
  - "${PORT:-3000}:3000"

docker compose --env-file ./config/.env.dev up -d

3Verify

docker compose config prints a real port number.

docker compose config | grep -A3 ports

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

A port mapping is not written as a quoted string

1Check

The services reference says HOST:CONTAINER should always be a quoted string, because unquoted values can be read by YAML as base-60 numbers.

grep -n -A3 'ports:' compose.yaml

2Fix

Quote the pair, or use the long syntax with target and published.

ports:
  - "8080:80"
  - target: 80
    published: "8081"
    protocol: tcp

3Verify

The file validates with no output errors.

docker compose config -q

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

environment or command uses the wrong shape

1Check

environment accepts a map or a list of KEY=value items. command accepts a string or a list. A healthcheck test list must start with NONE, CMD or CMD-SHELL.

docker compose config 2>&1 | head -20

2Fix

Rewrite the value in one of the documented forms.

environment:
  RACK_ENV: development
  SHOW: "true"
command: ["bundle", "exec", "thin", "-p", "3000"]
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]

3Verify

Validate again.

docker compose config -q

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Run docker compose config in CI so a bad file fails before deploy.
  • Give every variable in ports a default with ${VAR:-default}, or require it with ${VAR:?message}.
  • Quote every HOST:CONTAINER port pair.
  • Keep .env next to the compose file.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.