How to fix invalid port specification in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 325 views

The 'invalid port specification' error occurs when Docker cannot parse a port value correctly. This is commonly caused by YAML parsing port numbers as base-60 values, incorrect port syntax, or invalid port numbers. The fix usually involves quoting port mappings in docker-compose.yml or correcting the port format.

Quick fix

Fixes invalid port specification

# Wrong - YAML may interpret this as base-60
ports:
  - 2222:22
  - 8025:25

# Correct - always quote port mappings
ports:
  - "2222:22"
  - "8025:25"
  - "8080:80"
  1. Quote port mappings in docker-compose.yml
  2. Verify port syntax format
  3. Fix EXPOSE instruction in Dockerfile
  4. Check environment variables for ports
docker — error
# Wrong - YAML may interpret this as base-60
ports:
  - 2222:22
  - 8025:25
# Correct - always quote port mappings
ports:
  - "2222:22"
  - "8025:25"
  - "8080:80"
invalid port specification

What this error means

The "invalid port specification" error in Docker indicates that the port value you've provided cannot be parsed as a valid port number or port mapping. Docker expects ports to follow specific formats, and several common mistakes can trigger this error. The most frequent cause is a quirk in YAML 1.1 parsing: when you write a port mapping like `2222:22` without quotes in a docker-compose.yml file, YAML interprets it as a base-60 number (similar to time notation). This results in Docker receiving a completely different number than intended - for example, `2222:22` becomes `133342` (calculated as 2222 * 60 + 22), which is not a valid port. This error can also occur when using incorrect separators (like `/` instead of `:`), specifying ports outside the valid range (1-65535), or including invalid characters in the port specification. In Dockerfiles, the EXPOSE instruction has its own specific format requirements that differ from runtime port mapping.

Typical symptoms

  • Docker or docker-compose fails with 'invalid port specification' followed by an unexpected number
  • Error message shows a port number you didn't specify (like 133342 instead of 2222:22)
  • docker-compose up fails when starting services with port mappings
  • Dockerfile build fails at an EXPOSE instruction
  • Error mentions 'Cannot create container for service' with invalid port
  • Port bindings work from command line but fail in docker-compose.yml

Common causes

  1. Port mapping in docker-compose.yml not quoted, causing YAML base-60 parsing (most common when container port is below 60)
  2. Using incorrect separator (/ instead of :) in port specification
  3. Port number outside valid range (must be 1-65535)
  4. EXPOSE instruction in Dockerfile includes host-port mapping or IP address (incorrect format)
  5. Environment variable for port is not defined or evaluates to empty string
  6. Leading colon in port notation (e.g., ':8080:80')
  7. Trailing comma or extra characters in port specification
  8. Older docker-compose version with parsing bugs

How to fix "invalid port specification"

1Quote port mappings in docker-compose.yml

The most common fix is to wrap port mappings in quotes to prevent YAML base-60 parsing:

yaml
# Wrong - YAML may interpret this as base-60
ports:
  - 2222:22
  - 8025:25

# Correct - always quote port mappings
ports:
  - "2222:22"
  - "8025:25"
  - "8080:80"

This issue only affects port mappings where the container port (right side) is less than 60. Ports like 3306:3306 or 8080:80 work without quotes because numbers 60 and above aren't interpreted as base-60. However, it's best practice to always quote port mappings.

2Verify port syntax format

Ensure you're using the correct port specification format:

bash
# Docker run - correct format
docker run -p 8080:80 nginx           # hostPort:containerPort
docker run -p 127.0.0.1:8080:80 nginx # ip:hostPort:containerPort
docker run -p 80 nginx                 # containerPort only (random host port)

# Wrong formats
docker run -p 8080/80 nginx           # Wrong separator
docker run -p :8080:80 nginx          # Leading colon
docker run -p "8080:80:" nginx        # Trailing colon

In docker-compose.yml:

yaml
# Correct formats
ports:
  - "8080:80"                  # HOST:CONTAINER
  - "127.0.0.1:8080:80"        # IP:HOST:CONTAINER
  - "8080:80/udp"              # With protocol

# Wrong formats
ports:
  - "8080/80"                  # Wrong separator
  - ":8080:80"                 # Leading colon
3Fix EXPOSE instruction in Dockerfile

The EXPOSE instruction in a Dockerfile should only specify the container port and optionally the protocol - not host ports or IP addresses:

dockerfile
# Correct EXPOSE usage
EXPOSE 80
EXPOSE 8080/tcp
EXPOSE 443/tcp
EXPOSE 53/udp

# Wrong - don't include host port or IP
EXPOSE 80:80        # Invalid - no host mapping
EXPOSE 127.0.0.1:80:80  # Invalid - no IP address
EXPOSE 8080,        # Invalid - trailing comma

Note: EXPOSE is purely documentation - it doesn't actually publish the port. Use -p at runtime to publish ports.

4Check environment variables for ports

If you're using environment variables for ports, ensure they're properly defined:

yaml
# docker-compose.yml
services:
  web:
    ports:
      - "${HOST_PORT}:80"

# .env file (must exist and define the variable)
HOST_PORT=8080

Note: Variables from env_file are only available inside the container, not in docker-compose.yml. Define port variables in a .env file in the same directory as docker-compose.yml.

Test that your variable is defined:

bash
docker-compose config

This will show the interpolated values and reveal any undefined variables.

5Validate port numbers are in range

Port numbers must be between 1 and 65535:

bash
# Valid port numbers
docker run -p 80:80 nginx      # Standard HTTP
docker run -p 8080:80 nginx    # Common dev port
docker run -p 65535:80 nginx   # Maximum valid port

# Invalid port numbers
docker run -p 0:80 nginx       # 0 is invalid
docker run -p 70000:80 nginx   # Exceeds 65535
docker run -p -1:80 nginx      # Negative invalid

If you calculated a port number programmatically, verify the result is within the valid range.

6Update docker-compose to latest version

Some older versions of docker-compose had bugs with port parsing. Update to the latest version:

bash
# Check current version
docker-compose --version

# Update using pip (if installed via pip)
pip install --upgrade docker-compose

# Or use Docker Compose V2 (recommended)
docker compose version

# Docker Desktop users: Update Docker Desktop to get the latest docker-compose

Docker Compose V2 (invoked as docker compose without hyphen) is the recommended modern version and handles port specifications more reliably.

Advanced notes

### Understanding YAML Base-60 Parsing

YAML 1.1 includes support for "sexagesimal" (base-60) numbers, historically used for time notation. The format xx:yy is interpreted as xx * 60 + yy:

| Written | Parsed As | Result |
|---------|-----------|--------|
| 2222:22 | 2222*60+22 | 133342 |
| 8025:25 | 8025*60+25 | 481525 |
| 1:30 | 1*60+30 | 90 |

This only triggers when both numbers are valid (the right side must be < 60). Ports like 8080:80 don't trigger this because 80 >= 60.

### Docker Compose Port Syntax Reference

The full port syntax in docker-compose.yml:

yaml
ports:
  # Short syntax
  - "3000"                    # Container port (random host port)
  - "3000-3005"               # Port range
  - "8080:80"                 # HOST:CONTAINER
  - "9090-9091:8080-8081"     # Port range mapping
  - "127.0.0.1:8080:80"       # IP:HOST:CONTAINER
  - "127.0.0.1:8080:80/udp"   # With protocol
  - "6060:6060/udp"           # UDP protocol

  # Long syntax (more explicit)
  - target: 80
    published: 8080
    protocol: tcp
    mode: host

The long syntax avoids YAML parsing issues entirely and is more readable for complex configurations.

### Expose Port Ranges

When exposing port ranges in Dockerfile or docker-compose.yml:

dockerfile
# Dockerfile - expose a range
EXPOSE 7000-7100
yaml
# docker-compose.yml - map a range (quotes required!)
ports:
  - "7000-7100:7000-7100"

### Debugging Port Issues

To debug port parsing issues:

bash
# See how docker-compose interprets your file
docker-compose config

# Check container port bindings after creation
docker inspect <container> --format='{{.NetworkSettings.Ports}}'

# List all port mappings for running containers
docker ps --format "table {{.Names}}	{{.Ports}}"

Frequently asked questions

What does "invalid port specification" mean?
The "invalid port specification" error in Docker indicates that the port value you've provided cannot be parsed as a valid port number or port mapping. Docker expects ports to follow specific formats, and several common mistakes can trigger this error. yml file, YAML interprets it as a base-60 number (similar to time notation).
How do I fix "invalid port specification"?
The 'invalid port specification' error occurs when Docker cannot parse a port value correctly. This is commonly caused by YAML parsing port numbers as base-60 values, incorrect port syntax, or invalid port numbers. The fix usually involves quoting port mappings in docker-compose.yml or correcting the port format.
What causes "invalid port specification"?
Port mapping in docker-compose.yml not quoted, causing YAML base-60 parsing (most common when container port is below 60) Using incorrect separator (/ instead of :) in port specification Port number outside valid range (must be 1-65535)
Is the "invalid port specification" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading