What causes "invalid type %T for healthcheck.test" in docker/cli?

Use a string: `healthcheck: { test: curl -f http://localhost }`.

invalid type %T for healthcheck.test

Error message

invalid type %T for healthcheck.test

What it means

Thrown by transformHealthCheckTest for a service's `healthcheck.test`. It accepts a string (auto-wrapped as CMD-SHELL) or a list (CMD/CMD-SHELL + args). Any other type (map, int, bool) is rejected.

Solutions

Use a string: `healthcheck: { test: curl -f http://localhost }`.
Or a list: `healthcheck: { test: [CMD, curl, -f, http://localhost] }`.

Example fix

# before
web:
  healthcheck:
    test:
      cmd: curl
# after
web:
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost"]

Defensive patterns

Strategy: type-guard

Validate before calling

func validateHealthcheckTest(test any) error {
    switch test.(type) {
    case string, []any:
        return nil
    default:
        return fmt.Errorf("healthcheck.test must be string or list, got %T", test)
    }
}

Type guard

func isHealthcheckTest(v any) bool {
    switch v.(type) {
    case string, []any:
        return true
    }
    return false
}

Prevention

Use a string (CMD-SHELL) or a list (CMD + args) for healthcheck.test.
Don't use a map form for test.
Lint with `docker compose config`.

When it happens

Trigger: A service defines `healthcheck: { test: { cmd: curl } }` (map) or `test: 1` instead of a string/list.

Common situations: Using a map form that compose doesn't support; templating that yields a non-string.

Related errors

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

Appendix: source

Thrown at cli/compose/loader/loader.go:892

	}
	panic(fmt.Errorf("expected a map or a list, got %T: %#v", mappingOrList, mappingOrList))
}

var transformShellCommand TransformerFunc = func(value any) (any, error) {
	if str, ok := value.(string); ok {
		return shlex.Split(str)
	}
	return value, nil
}

var transformHealthCheckTest TransformerFunc = func(data any) (any, error) {
	switch value := data.(type) {
	case string:
		return append([]string{"CMD-SHELL"}, value), nil
	case []any:
		return value, nil
	default:
		return value, fmt.Errorf("invalid type %T for healthcheck.test", value)
	}
}

var transformSize TransformerFunc = func(value any) (any, error) {
	switch value := value.(type) {
	case int:
		return int64(value), nil
	case string:
		return units.RAMInBytes(value)
	}
	panic(fmt.Errorf("invalid type for size %T", value))
}

var transformStringToDuration TransformerFunc = func(value any) (any, error) {
	switch value := value.(type) {
	case string:
		d, err := time.ParseDuration(value)
		if err != nil {

View on GitHub (pinned to 4f84911bfe)