kubernetes/kubernetes · error

field label does not support subscript: %s

Error message

field label does not support subscript: %s

What it means

Thrown by ConvertDownwardAPIFieldLabel() when the label contains a subscript (e.g. 'metadata.annotations[foo]') but the subscripted base path is not 'metadata.annotations' or 'metadata.labels'. Only those two fields support subscripted access in downward-API field selectors; any other subscripted path is unsupported.

Source

Thrown at pkg/apis/core/pods/helpers.go:71

	}
	return true
}

// ConvertDownwardAPIFieldLabel converts the specified downward API field label
// and its value in the pod of the specified version to the internal version,
// and returns the converted label and value. This function returns an error if
// the conversion fails.
func ConvertDownwardAPIFieldLabel(version, label, value string) (string, string, error) {
	if version != "v1" {
		return "", "", fmt.Errorf("unsupported pod version: %s", version)
	}

	if path, _, ok := fieldpath.SplitMaybeSubscriptedPath(label); ok {
		switch path {
		case "metadata.annotations", "metadata.labels":
			return label, value, nil
		default:
			return "", "", fmt.Errorf("field label does not support subscript: %s", label)
		}
	}

	switch label {
	case "metadata.annotations",
		"metadata.labels",
		"metadata.name",
		"metadata.namespace",
		"metadata.uid",
		"spec.nodeName",
		"spec.restartPolicy",
		"spec.serviceAccountName",
		"spec.schedulerName",
		"status.phase",
		"status.hostIP",
		"status.hostIPs",
		"status.podIP",
		"status.podIPs":

View on GitHub (pinned to b882c60b40)

Solutions

1. Use only 'metadata.annotations[<key>]' or 'metadata.labels[<key>]' for subscripted selectors.
2. For non-subscripted fields, drop the bracket syntax and use the flat path (e.g. 'metadata.name').
3. Review fieldpath.SplitMaybeSubscriptedPath behavior to confirm subscript is actually needed.

Example fix

# before
kubectl get pods --field-selector spec.containers[0].name=nginx

# after
kubectl get pods --field-selector metadata.labels[app]=nginx

func validateSubscriptedLabel(label string) error {
    path, _, ok := fieldpath.SplitMaybeSubscriptedPath(label)
    if !ok { return nil }
    if path != "metadata.annotations" && path != "metadata.labels" {
        return fmt.Errorf("field label does not support subscript: %s", label)
    }
    return nil
}

func supportsSubscript(label string) bool {
    path, _, ok := fieldpath.SplitMaybeSubscriptedPath(label)
    return !ok || path == "metadata.annotations" || path == "metadata.labels"
}

When it happens

Trigger: Querying pods with a field selector like 'spec.containers[0].name=...' or 'status.podIP[0]=...'; the SplitMaybeSubscriptedPath detects a subscript and the switch falls into the default branch.

Common situations: Assuming any pod field supports array/map subscripts; building selectors dynamically and appending '[key]' to arbitrary fields.

Related errors

• field label not supported: %s
• unsupported pod version: %s
• field label not supported: %s
• DRA driver name is empty
• static pods may not use ClusterTrustBundle projected volume

AI-assisted analysis of kubernetes/kubernetes@b882c60b40 (2026-08-07). Data as JSON: /api/errors/f67cc6ed7ba9b066. Report an issue: GitHub.