metadata.annotations: Too long: kubectl apply's stored configuration annotation exceeded the size limit

Client-side apply stores the whole manifest in an annotation, and annotations are capped at roughly 256 kB. A large manifest — usually a CRD with a big schema — exceeds it.

Applies to: All Kubernetes versions

What it means

Client-side kubectl apply records the applied manifest in the kubectl.kubernetes.io/last-applied-configuration annotation so it can compute a three-way merge next time. Annotations have a total size limit of about 256 kB, and a manifest large enough to approach that limit cannot be stored. In practice this means CustomResourceDefinitions with extensive OpenAPI schemas, which are routinely hundreds of kilobytes. The failure is confusing because the object itself is perfectly valid — only the bookkeeping annotation does not fit.

Most common causes

• A CustomResourceDefinition with a large embedded schema.
• A ConfigMap containing large embedded files.
• A manifest with a very large number of resources applied as one object.
• Generated manifests carrying substantial inline data.
• Repeated applies accumulating annotations from several tools at once.

How to diagnose it

1. Check the manifest's size — anything approaching 256 kB is the likely cause.
2. Read the error, which names metadata.annotations explicitly.
3. Check whether the object is a CRD, which is the usual case.
4. Inspect existing annotations on a similar object to see how much space the stored configuration occupies.

How to fix it

1. Use Server-Side Apply: kubectl apply --server-side. It tracks field ownership on the server and stores no configuration annotation, which removes the limit entirely.
2. Use kubectl create or kubectl replace for large one-off objects where merge semantics are not needed.
3. Move large embedded data out of manifests and into a volume or an object store.
4. Split very large manifests into separate objects.

Notes

Server-Side Apply is the general answer here and is worth adopting for its own sake: field ownership tracking makes multiple controllers managing one object work correctly, which client-side apply handles poorly regardless of size.

Related

• Error from server (Conflict) — The object was modified by someone else
• error validating data — The manifest does not match the schema

Sources

• Kubernetes documentation — Server-Side Apply
• Kubernetes documentation — Custom Resources
• Kubernetes documentation — Annotations