How to fix invalid label value in Kubernetes | DevErrors

How to fix "invalid label value"

1Identify which label value is invalid

Run kubectl apply and capture the error:

bash

kubectl apply -f pod.yaml
# Error: admission webhook "validation..." denied the request
# Field: spec.containers[0].resources.labels["env"]
# Message: invalid value "prod-123_test.val": ...

The error message usually specifies:
- The label key (e.g., "env")
- The invalid value (e.g., "prod-123_test.val")
- The validation rule violated

Inspect the resource YAML:

bash

kubectl get pod <pod-name> -o yaml | grep -A10 labels:

For debugging, use jsonpath:

bash

kubectl get pod <pod-name> -o jsonpath='{.metadata.labels}'

2Understand label value naming rules

Kubernetes label rules:

Valid characters:
- Letters: a-z, A-Z
- Digits: 0-9
- Hyphens: - (but not start/end)
- Underscores: _ (but not start/end)
- Dots: . (but not start/end)

Valid examples:
- myapp, v1-alpha, tier_backend, config.v2
- release-1.2.3, stage_qa

Invalid examples:
- my app (space)
- -myapp (starts with hyphen)
- myapp- (ends with hyphen)
- my/app (slash)
- my:app (colon)
- my.app. (ends with dot)
- my_app_prod_test_config_value_xyz (too long, >63 chars)
- MyApp (uppercase: OK for value, only lowercase in label key)

Length limit: 63 characters maximum

bash

# Check length
echo "my-label-value-here" | wc -c
# Output: 20 (within 63)

3Fix invalid label values in YAML

Edit the resource YAML and correct the label values:

yaml

# BEFORE (Invalid)
apiVersion: v1
kind: Pod
metadata:
  name: myapp
  labels:
    app: my app        # Invalid: contains space
    env: prod-123-     # Invalid: ends with hyphen
    tier: BACKEND      # Note: uppercase OK in value
spec:
  containers:
  - image: myapp

# AFTER (Valid)
apiVersion: v1
kind: Pod
metadata:
  name: myapp
  labels:
    app: myapp
    env: prod-123
    tier: backend
spec:
  containers:
  - image: myapp

Common fixes:
- Replace spaces with hyphens or underscores: my app → my-app
- Remove trailing/leading special characters: prod- → prod
- Shorten long values (truncate after 63 chars)
- Remove reserved characters: app/prod → app-prod

Apply the corrected YAML:

bash

kubectl apply -f pod.yaml

4Fix invalid label values with kubectl label command

If the pod already exists, use kubectl to update labels:

bash

# Remove invalid label
kubectl label pod <pod-name> app- -n <namespace>

# Add corrected label
kubectl label pod <pod-name> app=myapp --overwrite -n <namespace>

# Verify
kubectl get pod <pod-name> --show-labels

For bulk updates:

bash

# Remove invalid label from all pods
kubectl label pods --all env- -n <namespace>

# Add corrected label
kubectl label pods --all env=prod --overwrite -n <namespace>

# For specific selector
kubectl label pods -l tier=BACKEND tier=backend --overwrite -n <namespace>
kubectl label pods -l tier=BACKEND tier- -n <namespace>  # Remove old

5Validate label format before applying

Use kubectl dry-run to catch validation errors early:

bash

kubectl apply -f pod.yaml --dry-run=client

If validation fails, fix the YAML and retry.

For automated validation in CI/CD:

bash

#!/bin/bash
# Check label format
kubectl apply -f pod.yaml --dry-run=client -o yaml | grep -A10 labels: | awk '/^\ \ \ \ \ \ /{
  label=$2
  if (label !~ /^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$/ && label != "") {
    print "Invalid label value: " label
    exit 1
  }
}'

Or use validation tools:

bash

# Using kube-lint
kube-lint pod.yaml  # Checks label format

# Using kubeconform
kubeconform -strict pod.yaml

6Fix label names (keys) if confused with values

Note: Label names (keys) have different rules than values:

Label name rules:
- Optional prefix: DNS-like (e.g., example.com/) must end with /
- Name part: 1-63 characters, lowercase alphanumeric and hyphens
- Cannot start/end with hyphen

Valid label names:
- app, environment, tier
- example.com/env, my.org/config

Invalid label names:
- _app (underscore not allowed)
- App (must be lowercase)
- my/app (slash only allowed before name part)
- -app (cannot start with hyphen)

If the error mentions label name:

yaml

# Invalid name
metadata:
  labels:
    _app: myapp  # Invalid: underscore in name
    App: myapp   # Invalid: uppercase

# Fix
metadata:
  labels:
    app: myapp    # Valid
    myapp: value  # Valid

7Handle special values by encoding

If your value genuinely needs special characters (unlikely but possible):

Option A: Encode special characters
- Replace spaces with dashes: prod v1 → prod-v1
- Replace slashes with dashes: api/v2 → api-v2
- Use underscores instead of dots: config.v2 → config_v2

Option B: Shorten long values
If value > 63 characters, truncate:

bash

VALUE="very-long-application-name-with-many-components-that-exceeds-63"
VALUE_SHORT="${VALUE:0:63}"
kubectl label pod <pod> app="$VALUE_SHORT"

Option C: Use annotations for complex data
Labels are for selecting/grouping; annotations are for metadata:

yaml

metadata:
  name: myapp
  labels:
    app: myapp  # Simple, for selection
  annotations:
    description: "Complex value with spaces and special chars"
    version: "1.2.3-alpha+build.123"  # Allowed in annotations

8Implement label validation in CI/CD

Add pre-deployment validation:

Using kyverno policy:

yaml

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: validate-labels
spec:
  validationFailureAction: enforce
  rules:
  - name: check-app-label
    match:
      resources:
        kinds:
        - Pod
    validate:
      message: "Label app is required"
      pattern:
        metadata:
          labels:
            app: "?*"  # Must exist and not be empty
  - name: check-label-format
    match:
      resources:
        kinds:
        - Pod
    validate:
      message: "Label values must be lowercase alphanumeric"
      pattern:
        metadata:
          labels:
            app: "[a-z0-9]([-a-z0-9]*[a-z0-9])?"

Using validating webhook:
Create a webhook that validates labels on admission.

GitOps with ArgoCD:
Add pre-sync hook:

bash

kubectl apply -f pod.yaml --dry-run=client

How to fix invalid label value in Kubernetes

What this error means

Typical symptoms

Common causes

How to fix "invalid label value"

Advanced notes

Related errors

Official resources & further reading