> ## Documentation Index > Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Common Failure Scenarios > Layered troubleshooting guide for Gateway API routing, validating HTTPRoute, Gateway, listeners, TLS, DNS, backend services, ReferenceGrant and CRD issues. This lesson covers common failure scenarios and a practical, layered approach to isolating problems when using the Gateway API. Troubleshooting is faster and more reliable when you separate possible sources of failure (control plane, data plane, cluster resources, DNS, TLS/certificates, etc.) and validate each layer methodically from client to backend. Start by identifying which Gateway API resources are in the request path (for example, `HTTPRoute`, `Gateway`, Listener) and which cluster resources support the application (for example, `Service`, `Endpoints`, `Namespace`). Then validate each resource in sequence. Key areas to validate for an HTTPRoute * Attachment: Is the `HTTPRoute` attached to the expected `Gateway`? * Confirm the route references the Gateway using `parentRef`(s) or equivalent. * Verify the Gateway has accepted the route (check route conditions/status). * Listener: Is the Listener active and listening on the expected port? * Check the Listener status and ensure there are no port conflicts across Listeners (each Listener must use a unique port or unique port/protocol combination). * Backend service and endpoints: Does the backend `Service` exist and have healthy `Endpoints`? * Ensure the `Service` is in the expected `Namespace` and that `Endpoints` are populated. * Hostname and DNS: Is the hostname correct and resolvable? * Mistyped hostnames or DNS misconfigurations frequently cause routing failures before the request reaches the cluster. * Traffic weights and routing rules: Is traffic being routed to the intended targets? * Incorrect weight configuration across multiple backend targets can result in traffic not reaching the intended service. * Connectivity to backend: Are there network policies, port mismatches, or other issues preventing connection to the backend? * Check NetworkPolicy, service port mappings, and pod readiness. A diagram titled "Failure Scenarios" with an HTTPRoute at the top branching to component boxes. The branches lead to nodes labeled Attachment, BackEnd, Hostname, Weight and downstream items like Listener, Namespace, Endpoints, Service, DNS and GatewayRef. Gateway-focused checks (what to validate and why) * Listener and port configuration * Ensure Listeners are bound to unique ports or unique port/protocol combinations. * Confirm the Gateway status reports each Listener as `Ready`. * TLS and certificate validation * Common problems: expired certificate, wrong certificate type, or incorrect secret/certificate reference (`secretRef`/`certificateRef`) in the Gateway Listener. * Inspect the Secret referenced by the Gateway and use OpenSSL to validate the certificate chain served by the Gateway endpoint. * Cross-namespace references and ReferenceGrant * If the Gateway and the certificate Secret live in different namespaces, a `ReferenceGrant` must permit the cross-namespace reference. Missing or incorrectly-scoped `ReferenceGrant`s will block TLS resolution. * CRDs and controller installation * If Gateway API CRDs were not installed (or were installed incorrectly), the Gateway controller will not recognize or reconcile custom resources. Check CRD presence and controller logs after installation via Helm or other installers. Quick commands to investigate common issues Replace resource names and namespaces with your actual values. ```bash theme={null} # Inspect the HTTPRoute to confirm parentRefs and route status/conditions kubectl get httproute example-route -o yaml # Inspect Gateway and its listeners/conditions kubectl get gateway example-gateway -o yaml # Ensure the Service and Endpoints exist in the expected namespace kubectl get svc example-service -n my-namespace kubectl get endpoints example-service -n my-namespace # Inspect the Secret referenced by the Gateway for TLS data kubectl get secret example-tls-secret -n cert-namespace -o yaml # Use OpenSSL to verify TLS certificate and chain from the Gateway IP/hostname:port openssl s_client -connect gateway.example.com:443 -servername gateway.example.com ``` Troubleshooting is iterative. You may check a Listener, then Gateway status, then a Secret, and then return to the `HTTPRoute` as new clues appear. Work from the outer layer (client/DNS) inward to the backend and iterate until the issue is isolated. A flowchart titled "Failure Scenarios" showing a Gateway at the top branching to components like Listeners, TLS, ReferenceGrant and CRDs, with downstream nodes such as Ports, Certificate, Name and Namespace (and a Helm icon). The diagram maps potential failure points and relationships between these Kubernetes/networking elements. Summary checklist | Area | What to check | Typical commands | | - | - | - | | Route attachment | `HTTPRoute` references and accepted status | `kubectl get httproute -o yaml` | | Listener & ports | Listener readiness, port uniqueness, protocol | `kubectl get gateway -o yaml` | | TLS / certificate | Secret reference, cert validity, chain | `kubectl get secret -n -o yaml` + `openssl s_client` | | Cross-namespace access | `ReferenceGrant` allows secret access | `kubectl get referencegrant -n ` | | Backend connectivity | `Service`, `Endpoints`, pod readiness | `kubectl get svc,ep -n `; `kubectl get pods -o wide -n ` | | Installation & CRDs | Gateway API CRDs present, controller running | `kubectl get crd \| grep gateway` ; check controller logs | These checks cover the most common failure points for Gateway API routing but are not exhaustive. Use the process above to narrow down the cause and reproduce the failure in a controlled way so you can apply a targeted fix. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.