Rules out the wrong-cluster case first, then checks whether the resource is a CRD that was never applied, isn't yet Established, or is being hidden from discovery by RBAC or a broken aggregated API. It does not cover ordinary typos in a resource name that IS registered — kubectl's own suggestion output usually catches those — and it is not a guide to writing CRDs.
Unverifiedno reproductions yetWhy this confidence?8 steps. Every step is written out below in full — the interactive version simply follows the branches for you.
Kubernetes' supported kubectl-to-API-server version skew is +/-1 minor version and does not, on its own, make a resource type disappear — for a built-in resource this error essentially never means version skew. It means the API server kubectl is actually talking to right now doesn't have that resource type registered at all.
What happens next
The single most common cause of this error is simply querying the wrong cluster.
kubectl config current-context && kubectl cluster-infoExpected result
staging-cluster
Kubernetes control plane is running at https://staging-api.example.com:6443What happens next
This lists every resource type the API server currently knows about, built-in or custom.
kubectl api-resources -o wide | grep -i <resource-name>Expected result
(no output)What happens next
If the current context points at a different cluster than intended, switch and retry before investigating anything else.
Changes system or service state. Review before running.
Changes kubectl's active context for all subsequent commands using this kubeconfig; it does not read or modify any credentials, only which cluster/context is currently selected.
kubectl config use-context <correct-context>The resource isn't listed at all — for anything that isn't a Kubernetes built-in, it needs its CRD applied to this cluster before it can be used, as a one-time, cluster-scoped step separate from creating instances of the resource.
kubectl get crd | grep -i <resource-plural>.<group>Expected result
(no output)What happens next
The resource IS listed by api-resources, yet kubectl still errors on it — this points at API discovery, not registration. Either RBAC is restricting the current identity's access to the discovery endpoints for that API group, or (for an aggregated API server, not a plain CRD) the backing APIService is unavailable. Check for APIServices reporting Available=False.
kubectl get apiservices | grep FalseExpected result
v1beta1.metrics.k8s.io metrics-server/metrics-server False (FailedDiscoveryCheck) 3hNo matching CRD exists on this cluster. Apply the manifest that defines it — this is separate from, and must happen before, creating any actual custom resource of that type.
Changes system or service state. Review before running.
Registers the CustomResourceDefinition cluster-wide, making the resource type available in every namespace; existing custom resource objects elsewhere are unaffected, but any controller expected to own this CRD needs to already be compatible with its schema.
kubectl apply -f <crd-manifest>.yamlThe CRD is present but the resource still doesn't show in api-resources. Check the CRD's own status — the API server only serves the resource once its Established condition is True, and there can be a brief window right after apply where it isn't yet. Also check whether the CRD is Namespaced or Cluster scoped and whether it's being queried the wrong way (a cluster-scoped resource queried with -n <namespace> can look absent).
kubectl get crd <resource-plural>.<group> -o jsonpath='{.status.conditions}'Expected result
[{"type":"Established","status":"True",...},{"type":"NamesAccepted","status":"True",...}]What would strengthen it: 6 more independent reproductions. Reproductions from 3 more distinct environments.