Kubernetes "unable to recognize ... no matches for kind" (CRD not installed) in CI

By Daniel Zoghalchali·Latchkey

This error means kubectl tried to apply an object of a kind the cluster does not recognize. For custom resources it almost always means the CRD that defines the kind has not been installed (or not yet established) before the CR is applied.

What this error means

kubectl apply fails with unable to recognize "x.yaml": no matches for kind "Foo" in version "example.com/v1". The CR (and anything after it) does not apply.

error: unable to recognize "release.yaml": no matches for kind
"Certificate" in version "cert-manager.io/v1"

Diagnose it: read events and previous logs

kubectl --context "$KUBE_CONTEXT" -n "$NS" get pods -o wide
kubectl -n "$NS" describe pod <pod> | sed -n "/Events/,$p"
kubectl -n "$NS" logs <pod> --previous --tail=50

Common causes

CRD not installed

The CRD defining the kind (cert-manager, Argo, an operator) is not present in the cluster.

CRD and CR applied together / out of order

A single kubectl apply -f bundle includes both the CRD and a CR using it; the CR is processed before the CRD is established.

How to fix it

Install the CRD first

Apply CRDs, wait for them to be Established, then apply the custom resources.

kubectl apply -f crds/
kubectl wait --for=condition=Established crd/certificates.cert-manager.io --timeout=60s
kubectl apply -f release.yaml

Confirm the kind/version exists

1. Check kubectl api-resources | grep <kind> to confirm registration.
2. Match the CR apiVersion to the installed CRD version exactly.
3. Order the pipeline: CRDs -> wait Established -> CRs.

How to prevent it

• Install and wait for CRDs before applying custom resources.
• Keep CRDs in a separate apply phase from CRs in CI.
• Pin operator/CRD versions so the CR apiVersion stays valid.

Frequently asked questions

Related guides

References

• Kubernetes documentation
• GitHub Actions documentation