☸️ Kubernetes Error Guide: 'metadata.annotations: Too long: must have at most 262144 bytes' on kubectl apply

Overview

metadata.annotations: Too long: must have at most 262144 bytes is an admission error from kubectl apply telling you the object’s annotations exceed the 256 KiB (262144-byte) limit the API server enforces on a single field. The usual culprit is the kubectl.kubernetes.io/last-applied-configuration annotation that client-side apply writes: for large CRDs, ConfigMaps, or heavily-templated manifests, this stored copy of your entire manifest can blow past the cap.

Client-side apply stores a full JSON copy of the last-applied manifest inside an annotation so it can compute three-way merge diffs. When your resource is large, that annotation alone can approach or exceed 256 KiB, and the apply is rejected. The fix is almost always to stop relying on that annotation by moving to server-side apply, which tracks field ownership on the server instead.

This is a mechanics-of-apply problem, not a broken resource. The object may be perfectly valid; it is only the accumulated annotation metadata that is too big.

Symptoms

The ConfigMap "app-bundle" is invalid: metadata.annotations: Too long:
must have at most 262144 bytes

You may also see it on Custom Resources or Deployments with large embedded payloads. kubectl apply fails while kubectl create or kubectl replace of the same file may succeed, which is a strong hint the problem is the last-applied annotation rather than the spec itself.

Common Root Causes

1. Bloated last-applied-configuration annotation

Client-side kubectl apply writes your whole manifest into kubectl.kubernetes.io/last-applied-configuration. For large objects this single annotation approaches the 256 KiB field limit.

2. Large data embedded directly in the object

ConfigMaps or Secrets holding large files, or CRDs with big inline schemas/payloads, push both the spec and its mirrored annotation over the limit.

3. Repeated applies accumulating metadata

Tools or GitOps controllers that re-apply large manifests keep rewriting the annotation, and combined with other annotations the total exceeds the cap.

4. Generated manifests with verbose annotations

Helm, Kustomize, or CI pipelines that stamp many large annotations (checksums, full configs) onto one object add to the same 256 KiB budget.

Diagnostic Workflow

Step 1: Confirm which object and field is oversized

kubectl apply -f manifest.yaml

Note the object name in the error; that is the one whose annotations are too large.

Step 2: Measure the last-applied annotation

kubectl get configmap app-bundle -o jsonpath='{.metadata.annotations.kubectl\.kubernetes\.io/last-applied-configuration}' | wc -c

A value near or over 262144 confirms the annotation is the problem.

Step 3: Check the total size of the manifest you are applying

wc -c manifest.yaml

If the manifest itself is large, client-side apply will mirror it into the annotation.

Step 4: List all annotations to spot other large contributors

kubectl get configmap app-bundle -o jsonpath='{.metadata.annotations}' | wc -c

Step-by-Step Resolution

1. Switch to server-side apply, which does not use the last-applied annotation at all. This is the durable fix:

   kubectl apply -f manifest.yaml --server-side --field-manager=my-ci

2. If the object already carries a huge last-applied annotation from prior client-side applies, migrate ownership and drop the annotation:

   kubectl apply -f manifest.yaml --server-side --force-conflicts

   Server-side apply removes reliance on the annotation going forward.

3. If you must stay on client-side apply for now, strip the annotation and use replace instead:

   kubectl replace -f manifest.yaml

   replace does not write the last-applied annotation, sidestepping the limit.

4. If the object is a ConfigMap or Secret holding large data, move that data out of the object. Mount it from a file/volume or split it into multiple smaller objects so no single object nears the cap.

5. Remove a stale last-applied annotation from an existing object explicitly if needed:

   kubectl annotate configmap app-bundle kubectl.kubernetes.io/last-applied-configuration- 

6. Re-apply and confirm success:

   kubectl apply -f manifest.yaml --server-side

   configmap/app-bundle serverside-applied

Prevention

• Standardize on server-side apply (kubectl apply --server-side) across pipelines and GitOps controllers; it eliminates the last-applied annotation entirely.
• Keep individual objects small: do not embed large files in ConfigMaps or Secrets, and split big bundles into multiple resources.
• Set a consistent --field-manager name so server-side apply tracks ownership cleanly and conflicts are meaningful.
• Audit generated manifests for oversized annotations (full config dumps, large checksums) before they hit the cluster.
• Review large CRD payloads in CI. The DevOps AI prompt library has prompts for refactoring bloated manifests and adopting server-side apply.

Related Errors

• metadata.annotations: Too long on other controllers — the same 256 KiB field cap hit by an operator that stores state in annotations.
• request entity too large — a separate size limit on the whole request body, not a single field.
• Apply failed with N conflicts — server-side apply detecting field-ownership conflicts; resolve with --force-conflicts.
• the object has been modified; please apply your changes to the latest version — an optimistic-concurrency conflict, unrelated to annotation size.

Frequently Asked Questions

What is the 262144-byte limit? It is the API server’s 256 KiB maximum size for a single metadata field, including any one annotation. Exceeding it on metadata.annotations rejects the object.

Why does the last-applied-configuration annotation get so big? Client-side kubectl apply stores a full JSON copy of your manifest in that annotation to compute merge diffs. For large objects the copy alone can approach 256 KiB.

Does server-side apply fix this permanently? Yes. Server-side apply tracks field ownership on the API server and does not write the last-applied annotation, so the bloat that causes this error never accumulates.

Can I just delete the annotation? You can remove it with kubectl annotate ... last-applied-configuration-, but if you keep using client-side apply on a large manifest it will come back. Moving to server-side apply is the real fix.

Why does kubectl replace work when apply fails? kubectl replace does not write the last-applied-configuration annotation, so it avoids the oversized-field problem, though it lacks apply’s three-way merge. For more kubectl workflows, see the Kubernetes & Helm guides.