Knowledge Vault

Docker template field validation

2 min read

Docker template field validation

Validate Docker Go template fields against the specific command’s documentation before use.

Context

Docker commands like docker ps, docker inspect, and docker container ls use Go template syntax for custom output formatting. However, the available template fields differ between commands—fields valid for docker inspect may not exist in docker ps.

Problem

# WRONG: Using inspect-only field with ps command
docker ps --format "{{.Health}}"
# Error: Template parsing error: template: :1:2: executing "" at <.Health>: can't evaluate field Health
 
# This fails silently in some versions, returning empty output

The {{.Health}} field exists in docker inspect output but not in docker ps format strings. The docker ps command uses {{.State}} instead.

Solution

Always verify template fields against the specific command’s documentation:

# CORRECT: Use the right field for each command
docker ps --format "{{.State}}"
 
# For detailed health info, use inspect instead
docker inspect --format "{{.State.Health.Status}}" container_name

Reference the official Docker documentation or use --format '{{json .}}' to discover available fields:

# Discover available fields for any command
docker ps --format '{{json .}}' | jq 'keys'

Reusability

  • Score: 4/5
  • Used in: aloysiusproductions-ops-core runner health checks

Trade-offs

  • Pro: Prevents silent failures in CI scripts
  • Pro: Makes template usage explicit and documented
  • Con: Requires consulting docs for each command
  • Con: Field names may change between Docker versions

Source

Discovered during workflow audit on 2026-01-23. Commit 72f0c42 fixed {{.Health}} → {{.State}} in runner health monitoring script.

Graph View

Backlinks