Docker Compose "services.<name> must be a mapping" in CI

Compose expects each service to be a mapping of keys (image, ports, ...). services.<name> must be a mapping means the service was written as a scalar, a list, or left empty - so its body is not the key/value structure Compose requires.

What this error means

A docker compose config/up fails with services.<name> must be a mapping (or ... contains an invalid type, it should be an object). The named service has no proper key/value body.

docker

services.api must be a mapping
# services:
#   api:            <- nothing indented under it, so it parses as null
#   web:
#     image: nginx

Common causes

An empty service body

A service key with nothing indented beneath it parses as null, not a mapping, and Compose rejects it.

The service written as a scalar or list

Assigning a string or a YAML list to a service name instead of a key/value block fails the mapping requirement.

Indentation collapses the service body

Under-indented keys that do not nest under the service name leave the service effectively empty.

How to fix it

Give the service a proper mapping body

Indent at least one key (like image) under the service name.

docker-compose.yml

services:
  api:
    image: myorg/api:1.4.2
    ports:
      - "8080:8080"

Remove or complete placeholder services

Delete empty service stubs or fill them in.

Terminal

docker compose config   # confirms each service is a valid mapping

How to prevent it

Give each service at least an image or build key.
Remove placeholder/empty service entries.
Run docker compose config to validate service structure.