Introduction

The jq error Cannot iterate over null appears frequently in Docker automation scripts that parse JSON from APIs, inspect output, or container metadata. The root cause is simple: your filter expects an array or object, but the actual value is null or missing. Robust parsing requires defensive filters that handle empty and absent data safely.

Core Sections

Why the error occurs

jq iteration operators such as .items[] assume .items is an array. If the field is null, iteration fails and the command exits with a non zero status. In CI pipelines, that single failure can stop image builds or deployment stages.

You can reproduce the problem quickly with mock data.

1cat <<'JSON' > /tmp/sample.json
2{
3  "services": null
4}
5JSON
6
7jq '.services[] | .name' /tmp/sample.json

The fix is to provide a safe default or optional iterator.

jq '.services // [] | .[] | .name' /tmp/sample.json
jq '.services[]? | .name' /tmp/sample.json

Defensive patterns for production scripts

For shell scripts, combine set -euo pipefail with explicit null tolerant filters. If data absence is valid, return an empty result instead of failing. If data is required, detect null and print a clear error before exit.

1#!/usr/bin/env bash
2set -euo pipefail
3
4json_input='{"services":null}'
5
6service_names=$(jq -r '.services // [] | .[] | .name' <<<"$json_input")
7if [[ -z "$service_names" ]]; then
8  echo "No services found. Continuing safely."
9else
10  echo "$service_names"
11fi

This approach keeps pipelines stable while preserving predictable behavior.

Validate shape before heavy processing

When input contracts are uncertain, validate the expected data shape first. It is better to fail early with a descriptive message than to continue with partial assumptions.

1#!/usr/bin/env bash
2set -euo pipefail
3
4json_input='{"services":[{"name":"api"},{"name":"worker"}]}'
5
6jq -e '.services | type == "array"' <<<"$json_input" >/dev/null || {
7  echo "Expected .services to be an array" >&2
8  exit 1
9}
10
11jq -r '.services[] | .name' <<<"$json_input"

Docker specific examples

Commands such as docker inspect can return null for optional sections depending on image or runtime configuration. Treat every optional field as potentially absent. Also prefer --format when Go templates can extract fixed values directly, then reserve jq for complex transformations.

A practical strategy is to capture command output once, persist to a temporary file, and run multiple jq checks from the same source. This improves repeatability and simplifies troubleshooting.

Common Pitfalls

• Iterating directly over optional fields with .field[] and assuming they always exist. Use []? or // [] instead.
• Treating null and empty array as identical business states without explicit handling. Decide whether absence means error or valid empty data.
• Ignoring exit codes when piping jq into other commands. Check failures early to avoid hidden downstream issues.
• Parsing Docker command output repeatedly with slight filter differences. Save output once and validate structure before extraction.
• Writing filters that are hard to read under incident pressure. Keep null handling obvious and add comments for critical paths.

Summary

• Cannot iterate over null means your filter expected iterable data but got null.
• Safe defaults like // [] and optional iterators like []? prevent brittle scripts.
• Validate JSON shape when input quality is uncertain.
• In Docker workflows, treat optional metadata as truly optional.
• Clear filter design and explicit error handling improve CI reliability.

Operational guidance

During incident response, print both the active jq filter and a redacted sample payload in logs. Teams often lose time because they debug only the filter or only the payload. Keeping both together makes null shape mismatches obvious and helps future maintainers understand why optional handling was added.

Additional implementation notes: validate assumptions with logs, tests, and environment checks before deployment so behavior stays predictable across upgrades.