Docker Compose says a service property contains an invalid type
The 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.
Fix it fast
1Find out which cause you have
Print the file after variable substitution. The broken value shows up in the output, usually empty.
docker compose config2Match what you see, then jump to its fix
- 1
A 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
The ports value looks like 22:22 or a number-like pair without quotesA port mapping is not written as a quoted stringFix - 3
The error names environment, command or healthcheck instead of portsenvironment or command uses the wrong shapeFix
- 1
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 .env2Fix
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 -d3Verify
docker compose config prints a real port number.
docker compose config | grep -A3 portsConfirmed by docs.docker.com
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.yaml2Fix
Quote the pair, or use the long syntax with target and published.
ports:
- "8080:80"
- target: 80
published: "8081"
protocol: tcp3Verify
The file validates with no output errors.
docker compose config -qConfirmed by docs.docker.com
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 -202Fix
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 -qConfirmed by docs.docker.com
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
Servers
apk cannot find py-pip in an Alpine Docker image
py-pip (no such package):
On current Alpine releases there is no package called py-pip.
2 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
AH00558: Apache in Docker cannot reliably determine its fully qualified domain name
Set the 'ServerName' directive globally to suppress this message
AH00558 is a warning, not a crash.
2 causes, each with a fixServers
Apache in a Docker container logs AH01114 when it proxies to a backend
AH01114: HTTP: failed to make connection to backend: api
Apache's proxy worker could not open a connection to the address in ProxyPass.
5 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fix