IMD SolutionComputing LibraryShop main store

Troubleshooting

Fixing the Docker Compose logging options must be a mapping error

Edge computing and IIoT Published 5 min read

Short answer

The error means the options key under logging is written as a YAML list. Delete the dash and give max-size and max-file their own key-value lines, redeploy the stack, and inspect the recreated container to confirm the runtime received both limits.

On this page
  1. Why options must be a mapping
  2. The corrected options block
  3. Where the equals-sign syntax comes from
  4. Redeploy and verify
  5. The same error at other keys
  6. Log budget for a Node-RED container capped at 10 MB per file and five files
  7. Questions asked

Portainer rejects the stack with services.node-red.logging.options must be a mapping because the options key under logging holds a YAML list. In the failing stack file, both settings sit behind one dash as a single string, max-size=10m,max-file=5. Compose validation requires options to be a mapping: each logging option gets its own key and value, with no dash. Delete the dash, write max-size: 10m and max-file: 5 on separate lines, redeploy the stack, and inspect the recreated container to confirm the runtime received both limits. Nothing else in the service definition — image, ports, volumes, networks — needs to change.

Why options must be a mapping #

YAML has two collection shapes, and this error is Compose saying it got the wrong one. A mapping pairs each key with a value on its own line. A list holds items marked with a dash. Under logging, the options key must be a mapping: option name as the key, option value as the value.

The failing block uses the list shape:

 logging:
 options:
 - "max-size=10m,max-file=5"

The dash turns options into a list, and the list holds one string that mashes both settings together. The draft therefore has two problems at once: the wrong collection type, and two options merged into one string the validator never reads as separate settings. Portainer passes the stack to Compose on deploy, Compose refuses the file at validation, and the path in the message — services.node-red.logging.options — names the exact key to fix.

Decision: when the error names logging.options, nothing else in the file is implicated. Fix the shape of that block and move on.

The corrected options block #

 logging:
 options:
 max-size: 10m
 max-file: 5

Each option is now its own key with its own value, at the indentation depth the block already had. Use spaces, not tabs — a tab used for indentation causes its own parse error. No equals sign and no quotes are needed: the compose form is key: value, unlike the other two surfaces below.

driver: json-file can sit above options when a service needs a named driver. This Node-RED service does not need the line: json-file is the default logging driver, and both of these options belong to it.

Decision: in this shape, the block passes the validation that rejected the list.

Where the equals-sign syntax comes from #

The max-size=10m form is not wrong everywhere — it is the syntax of two other Docker surfaces, which is how it ends up pasted into compose files:

  • The command line takes one flag per option: --log-opt max-size=10m, repeated for each option.
  • daemon.json takes quoted keys under log-opts: "max-size": "10m" and "max-file": "5".
  • A compose file takes key: value lines under the logging block — the corrected form above, with no equals sign and no dash.

When an example comes from a docker run command or a daemon.json snippet, retype each pair as a mapping entry before the stack will validate.

Redeploy and verify #

  • Paste the mapping in place of the dashed list and save the stack in Portainer.
  • Redeploy. The must be a mapping error should no longer appear, and the stack deploys.
  • Changing the logging block changes the service's configuration, so Compose recreates the container during the deploy — that recreation is what puts the new options in force. It also restarts Node-RED, so time the redeploy to suit the line.
  • Inspect the recreated container and read its log configuration back: both values you set should appear on it. A successful deploy proves the YAML shape, not that the limits are active, so this check is the one that closes the case.

Two notes while the file is open. The version: "3.7" line at the top is legacy: current Compose warns that it is obsolete and ignores it, and it plays no part in this error. And if Docker is more than the controller needs for this one service, installing Node-RED natively on a Linux edge computer removes container log rotation from the picture entirely.

The same error at other keys #

Compose reports the first structural fault it finds, so the same wording appears at other levels of the file, each with its own fix:

  • services must be a mapping points one level up: the services: key itself is indented wrong, or the legacy docker-compose binary is parsing the file instead of the compose plugin — the older binary predates current files and rejects valid ones. Run docker compose config on the host first; it prints the rendered configuration or the exact parse error without deploying anything. Which implementation parses the file matters on controller-class hardware too — compose CLI plugin an IOT2050 uses shows the check to make before blaming the file.
  • Top-level object must be a mapping means the parser saw no usable document; one reported cause was an empty compose file. Confirm the copy being deployed is the copy you edited — Portainer deploys the stack file it stores, not one sitting on your workstation.

Decision, case by case: an error naming a specific key means that block's shape; a services error means indentation or the parser; a top-level error means an empty or wrong file.

Log budget for a Node-RED container capped at 10 MB per file and five files #

Inputs, and where each comes from:

  • max-size: 10m — a per-file cap of 10 MB; the m suffix in a Docker size string reads as megabytes. Value from the stack being deployed.
  • max-file: 5 — five files retained. Same options block.

Rule: json-file rotation caps every file at max-size and keeps at most max-file of them, so the worst-case retained log size for the container is max-size × max-file.

Arithmetic: 10 MB × 5 = 50 MB.

Result: about 50 MB worst case for this container's logs, reached once all five files sit at the cap; before that, the footprint grows file by file toward the bound.

Decision: keep 10m and 5 when a 50 MB worst case is an acceptable share of the disk. When the disk is tight, lower max-size rather than max-file — at max-file 5, every 1 MB cut from the per-file cap lowers the bound by 5 MB. The bound also shares the disk with everything else the box stores: when a process or vibration data store lives alongside the logs, budget the 50 MB together with it, as laid out in choosing edge storage for high-rate vibration data.

Questions asked

Can I set log rotation once for every container on the host?

Yes. The Docker daemon reads a default logging driver and its options from daemon.json, so every container on that host rotates its logs without per-service entries in each compose file. A service that needs a different budget can still set its own options block in the compose file, and the service-level mapping overrides the host default.

Do logging options apply to a container that already exists?

No. The driver and its options are read when a container is created, so the running container keeps its old behavior until it is recreated. Redeploying the stack with a changed logging block recreates the service's container, and the old container's log files are discarded when it is removed.

How much log disk does the local logging driver use by default?

The local driver's documented default is 100 MB per container, based on five files of 20 MB each. If you use the local driver for its storage format, set max-size and max-file explicitly in the same options mapping when 100 MB per container is more than the box should carry.

Does a deploy that fails validation change anything on the host?

No. Compose validates the file structure before it creates or updates any container, so a failed deploy leaves the previously deployed services running unchanged. Fix the options block and redeploy; the only interruption is the recreation of the container whose configuration changed.

Keep reading

  • Troubleshooting

    Fixing a Docker shared library error on an edge PC

    A container on an edge PC that exits with an error while loading shared libraries was built for a different controller firmware generation than the one installed. Pull the image revision rebuilt for your firmware, recreate the container, and verify with ldd, the linker cache and a restart-count check. Never symlink across major library versions: on a machine driving physical outputs, a mismatched library produces wrong I/O data instead of a clean error.

    Edge computing and IIoT

  • How-to

    Install licensed software on an industrial edge PC

    Install vendor-licensed container software on an industrial edge PC by passing four gates in order: a purchased license with the installer obtained only from the vendor, a verified Docker engine, an installer build that matches the CPU, and a proven open-internet path before the pull. Vendor guidance budgets the install command at 30 minutes to 1 hour; at a 5 Mbit/s link a 2 GB payload alone needs about 53 of them.

    Edge computing and IIoT

  • How-to

    Run Python and Node-RED beside PLC code on an edge PC

    Keep the IEC 61131-3 program in the controller runtime and run Python and Node-RED as separate Docker containers on the same edge PC. Exchange data over one MQTT interface with a fixed publish period, and declare data stale after three missed periods. One container per workload, and nothing from Python or Node-RED inside the control project.

    Edge computing and IIoT