How to fix invalid port specification in Docker

DockerBEGINNERLOW

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 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.

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.

How to fix invalid port specification in Docker

What this error means

Typical symptoms

Common causes

How to fix "invalid port specification"

Advanced notes

Related errors

Official resources & further reading