Docker Compose "ports must be a mapping" in CI

A service's ports: is a list of port mappings - short strings like "8080:80" or long-form mapping entries with target/published. Writing ports: as a single mapping (key/value object) instead of a list makes Compose reject the type.

What this error means

A docker compose up/config fails validating ports: - it should be a list of strings or long-form entries but was given a bare mapping.

services.web.ports must be a list
# offending:
# ports:
#   8080: 80

Common causes

ports written as a key/value mapping

Using 8080: 80 (a YAML mapping) instead of a list item "8080:80" is the wrong type.

Long-form entries not given as list items

Long-form target/published must each be a list item, not nested mapping keys under ports:.

How to fix it

Write ports as a list of strings

1. Use list items with quoted host:container strings.

services:
  web:
    ports:
      - "8080:80"
      - "8443:443"

Use long-form list items

1. Express each mapping as a list item with target/published.

services:
  web:
    ports:
      - target: 80
        published: 8080
        protocol: tcp

How to prevent it

• Always write ports: as a YAML list.
• Quote short-form host:container strings.
• Validate with docker compose config.

Related guides