kubectl apply "unable to recognize": apiVersion mismatch debugging

TL;DR

"Unable to recognize" means the API server does not serve that apiVersion and kind combination: either the version was removed in an upgrade, the CRD is not installed, or the manifest targets the wrong cluster. Check what the server actually serves for that kind, then align the manifest. This error is the server telling you your manifest is from a different cluster's era.

The query

kubectl apply "unable to recognize": apiVersion mismatch debugging

Use this when

• kubectl apply fails with "unable to recognize"
• After cluster upgrades remove old API versions
• CRD-based resources fail to apply
• Manifests copied between clusters fail

Not for when

• YAML syntax errors (those fail client-side first)
• RBAC forbidden on apply
• Server-side apply conflicts

Steps

Step 1: Ask the server what it serves

Query the API discovery for the kind: list the available apiVersions for that resource. If none match your manifest, the version is gone or the CRD is missing. Expected output: the served versions for the kind, or confirmation it is not served at all.

Step 2: Check for removed API versions after upgrades

Each Kubernetes release removes deprecated APIs. If your manifest uses a version removed in the current release, update the manifest to a served version. The deprecation warnings from the last year were telling you this was coming. Expected output: the manifest migrated to a served apiVersion.

Step 3: Verify CRD installation for custom resources

For custom kinds, check that the CRD is installed in this cluster and that its served versions include your manifest's version. CRDs installed in staging but not production cause exactly this error. Expected output: CRD present with a matching served version, or the missing CRD identified.

Step 4: Confirm you are talking to the right cluster

Check the current context. Applying a manifest built for the new cluster against the old cluster (or vice versa) produces version mismatches that look like manifest bugs. Expected output: the target cluster confirmed as the intended one.

Step 5: Convert stored versions if needed

If objects already exist in storage under an old version, the API server usually converts automatically. When it cannot, a storage version migration is needed; check the release notes for the manual steps. Expected output: existing objects readable under the new version.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_X4XNAA-ZLu-rsNQpgh1aMw