docker/cli · error

invalid boolean

Error message

invalid boolean: %s

What it means

Returned by the toBoolean caster when an interpolated value for a boolean compose field is not one of the accepted YAML-bool tokens (loader/interpolate.go:63-71). Accepted values are y/yes/true/on (true) and n/no/false/off (false), case-insensitive; anything else fails.

Solutions

1. Use one of yes/no/true/false/on/off (case-insensitive) for the interpolated value.
2. Set the env var backing the field to a valid boolean token.
3. Provide a default in the interpolation, e.g. ${TTY:-false}.

Example fix

# before
environment:
  TTY_FLAG: enabled
services:
  app:
    tty: ${TTY_FLAG}
# after
environment:
  TTY_FLAG: "true"
services:
  app:
    tty: ${TTY_FLAG:-false}

var validBools = map[string]bool{
    "y": true, "yes": true, "true": true, "on": true,
    "n": true, "no": true, "false": true, "off": true,
}
func isValidBool(v string) bool {
    _, ok := validBools[strings.ToLower(v)]
    return ok
}
// if !isValidBool(os.Getenv("TTY")) { return fmt.Errorf("TTY must be yes/no/true/false/on/off") }

When it happens

Trigger: Setting a boolean-typed compose field (e.g. privileged, tty, read_only, healthcheck.disable, volumes.[].read_only, *.external) via interpolation to a value outside the accepted set. Reached at interpolate.go:70 via the TypeCastMapping toBoolean.

Common situations: Using 1/0 or enabled/disabled instead of true/false; an env var holding an unexpected string; locale-specific tokens like 'ja'/'nein'.

Related errors

• failed to cast to expected type
• invalid interpolation format for
• error while interpolating
• specify a Compose file (with --compose-file)
• cluster options are incompatible with type image

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/80d2cb6f2b3bfc49. Report an issue: GitHub.

Appendix: source

Thrown at cli/compose/loader/interpolate.go:70

}

func toInt(value string) (any, error) {
	return strconv.Atoi(value)
}

func toFloat(value string) (any, error) {
	return strconv.ParseFloat(value, 64)
}

// should match http://yaml.org/type/bool.html
func toBoolean(value string) (any, error) {
	switch strings.ToLower(value) {
	case "y", "yes", "true", "on":
		return true, nil
	case "n", "no", "false", "off":
		return false, nil
	default:
		return nil, fmt.Errorf("invalid boolean: %s", value)
	}
}

func interpolateConfig(configDict map[string]any, opts interp.Options) (map[string]any, error) {
	return interp.Interpolate(configDict, opts)
}

View on GitHub (pinned to 4f84911bfe)