Kubernetes YAML Validation: The 10 Most Common Manifest Mistakes

Kubernetes manifests define the desired state of containerized infrastructure. However, because YAML relies on whitespace and dynamic typing, tiny indentation or schema errors frequently slip past code reviews and crash deployment pipelines.

Here are the 10 most common Kubernetes YAML validation errors and how to fix them before running kubectl apply.

---

1. The "Norway Problem" (Unquoted Country Codes and Booleans)

In YAML 1.1, bare strings like NO, no, YES, yes, ON, off, TRUE, and false are parsed as booleans.

• The Bug: Setting country: NO results in country: false.
• The Fix: Always quote string values that resemble booleans or numbers:

env:
  - name: COUNTRY_CODE
    value: "NO"  # Must be in quotes
  - name: ENABLE_FEATURE
    value: "true"

---

2. Label Selector and Template Metadata Mismatch

In Deployments, the spec.selector.matchLabels must exactly match spec.template.metadata.labels.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app.kubernetes.io/name: api-service # Must match pod template
  template:
    metadata:
      labels:
        app.kubernetes.io/name: api-service

---

3. Missing CPU & Memory Requests and Limits

Omitting resource specifications leads to "noisy neighbor" resource starvation and OOMKilled pods under load.

resources:
  requests:
    cpu: "250m"
    memory: "256Mi"
  limits:
    cpu: "1000m"
    memory: "512Mi"

---

4. Port Number vs Port Name Types

Kubernetes Service targetPort can be an integer or a string name. Mixing types or using quotes where integers are expected can cause service discovery failures:

apiVersion: v1
kind: Service
metadata:
  name: web-svc
spec:
  ports:
    - port: 80
      targetPort: 8080 # Integer, or string matching containerPort name

---

5. Indentation Tab vs Space Violations

YAML strictly prohibits tab characters (\t) for indentation. A single tab will cause error: error converting YAML to JSON: yaml: line X: found character that cannot start any token.

Validate your manifests against official Kubernetes JSONSchemas using the DevFlow Kubernetes YAML Validator.