How to fix invalid label value in Kubernetes

KubernetesBEGINNERLOWUpdated Dec 6, 2025· 191 views

Invalid label values violate Kubernetes naming conventions, preventing resource creation or updates. Labels must follow specific rules for characters, length, and format.

Quick fix

Fixes invalid label value

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": ...
  1. Identify which label value is invalid
  2. Understand label value naming rules
  3. Fix invalid label values in YAML
  4. Fix invalid label values with kubectl label command
kubernetes — error
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": ...
invalid label value

What this error means

Kubernetes enforces strict label value validation: 1. Length: 0-63 characters (empty is valid) 2. Pattern: alphanumeric ([a-z0-9A-Z]), hyphens, underscores, dots 3. First/last character: must be alphanumeric (not hyphen, underscore, or dot) 4. Special characters not allowed: spaces, slashes, colons, pipes, etc. When you create or update a resource with an invalid label value, the API server rejects the request with a validation error.

Typical symptoms

  • kubectl apply shows "invalid value" or "validation failure"
  • Error message mentions label validation or naming rules
  • Cannot create pod with certain label values
  • Deployment update fails due to label validation
  • StatefulSet creation rejected for invalid label
  • API server returns 422 Unprocessable Entity
  • kubectl label command returns invalid format error

Common causes

  1. Label value contains spaces or special characters
  2. Label value starts or ends with hyphen, underscore, or dot
  3. Label value longer than 63 characters
  4. Label value contains capital letters (only valid in domain prefix)
  5. Label value contains slashes, colons, or pipes (reserved characters)
  6. Label name (key) invalid instead of value
  7. Copy-paste from external source with Unicode characters

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

Advanced notes

Label value validation is strict for good reasons: Kubernetes uses labels internally for selectors, and invalid formats break the selector logic. Case sensitivity matters: label keys are case-sensitive, and best practice is lowercase keys. Label values are case-sensitive too but can be mixed-case. For automated deployments, generate labels programmatically to avoid human error. Use label templating in your IaC (Terraform, Helm) with validation. For large organizations, establish label naming conventions and document them (e.g., "all app labels must start with team name"). Kyverno is the standard way to enforce label policies at cluster level. For multiple label validation rules, combine them in a single policy. Monitoring and alerting on label compliance helps catch issues early.

Frequently asked questions

What does "invalid label value" mean?
Kubernetes enforces strict label value validation: 1. Length: 0-63 characters (empty is valid) 2. Pattern: alphanumeric ([a-z0-9A-Z]), hyphens, underscores, dots 3.
How do I fix "invalid label value"?
Invalid label values violate Kubernetes naming conventions, preventing resource creation or updates. Labels must follow specific rules for characters, length, and format.
What causes "invalid label value"?
Label value contains spaces or special characters Label value starts or ends with hyphen, underscore, or dot Label value longer than 63 characters
Is the "invalid label value" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading