Docker Compose "services.X.build must be a string or object" in Builds

By Daniel Zoghalchali·Latchkey

Compose validated the build key of a service and found the wrong YAML type. build must be either a string (a context path) or a mapping (context, dockerfile, …) - not a list or scalar of another type.

What this error means

A docker compose build or up --build fails during config validation with services.<name>.build must be a string or object, before any image is built. The file otherwise looks reasonable.

services.api.build must be a string or object
# offending:
#   build:
#     - context: ./api      # a list, not a mapping

Common causes

build written as a list

A stray - turns the build mapping into a list (build:\n - context: ...). Compose expects either a bare path string or a key/value mapping, so a list is rejected.

Wrong indentation under the service

Misaligned indentation can make build’s children parse as something other than a mapping, or attach to the wrong service.

A scalar of the wrong shape

Setting build: to a number, boolean, or empty value (instead of a path string or mapping) fails the type check.

How to fix it

Use a valid string or mapping form

Either give a context path string, or a properly-indented mapping.

services:
  api:
    build: ./api            # string form
  web:
    build:                  # mapping form
      context: ./web
      dockerfile: Dockerfile

Validate the compose config

Render the resolved config to catch the type error before building.

docker compose config   # prints the parsed config or the validation error

How to prevent it

• Run docker compose config in CI to validate before building.
• Keep service keys consistently indented; avoid stray - under mappings.
• Lint compose files with a YAML schema-aware linter.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation