error validating data: The manifest does not match the schema for that resource

Validation rejects a manifest whose fields do not match the API schema — an unknown field, a wrong type, or a missing required value. The message names the exact path, which makes it one of the more mechanical errors to fix.

Applies to: All Kubernetes versions

What it means

Objects are validated against the schema for their kind and version, and a failure names the JSON path of the offending field: error validating data: ValidationError(Deployment.spec.template.spec): unknown field "container" in io.k8s.api.core.v1.PodSpec. Most of these are YAML mistakes rather than conceptual ones — a singular where the schema wants a plural, a string where it wants an integer, a block indented one level off so it lands in the wrong parent. The indentation case is the one worth watching for, because YAML will happily parse a structurally valid document that means something quite different from what was intended, and the resulting error points at the field rather than at the indentation that misplaced it.

Most common causes

• A misspelled field name, or a singular where the schema uses a plural.
• Incorrect indentation placing a field under the wrong parent.
• A type mismatch — a quoted number where an integer is required, or the reverse.
• A required field omitted.
• A field that exists in a different API version of the same kind.
• A field from a custom resource's newer schema applied against an older CRD.

How to diagnose it

1. Read the path in the error. It gives the exact location and the schema type it was validated against.
2. Check the field against the reference: kubectl explain deployment.spec.template.spec lists valid fields at any path.
3. Validate without applying: kubectl apply --dry-run=server -f manifest.yaml checks against the real schema.
4. Check indentation carefully around the reported path — a correct field name in the wrong place produces an unknown-field error.
5. For a custom resource, read the CRD's schema: kubectl get crd NAME -o yaml.

How to fix it

1. Correct the field name, type, or placement as the error indicates.
2. Use kubectl explain rather than guessing — it reflects the cluster's actual schema, which is more reliable than documentation for a different version.
3. Add server-side dry-run validation to CI so schema errors are caught before deployment.
4. Update the CRD if the manifest uses fields from a newer version of the custom resource.

Notes

Server-side dry-run validates against the real cluster schema including custom resources and admission webhooks, while client-side validation does not. For anything involving CRDs, the server-side form is the one that gives a trustworthy answer.

Related

• no matches for kind — The cluster does not recognise this resource type
• Error from server (Conflict) — The object was modified by someone else

Sources

• Kubernetes documentation — Kubernetes API Concepts
• Kubernetes documentation — Custom Resources
• Kubernetes documentation — kubectl Quick Reference