> ## 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.
# Demo The Power of Status Fields
> Walks through five Gateway API troubleshooting scenarios using NGINX Gateway Fabric, showing symptoms, status field inspection, root causes, and corrective steps
In this lesson we walk through five common Gateway API troubleshooting scenarios using the NGINX Gateway Fabric. For each case you'll see the observable symptom, how to inspect status fields and controller messages, the root cause, and the corrective steps to verify the fix.
***
Summary of scenarios
| Scenario | Symptom | Typical Root Cause | Quick Fix |
| - | - | - | - |
| 1 | Gateway shows `ADDRESS` empty / `PROGRAMMED = Unknown` | Wrong `spec.gatewayClassName` (typo) | Correct `gatewayClassName`, reapply |
| 2 | Gateway listener shows `Attached Routes: 0` despite an HTTPRoute present | Typo or incorrect `parentRefs` prevents route from referencing the Gateway | Fix `parentRefs.name` (or other fields), reapply |
| 3 | TLS certificate error: `Certificate ref ... not permitted by any ReferenceGrant` | Gateway referencing a Secret in another namespace without a `ReferenceGrant` | Create `ReferenceGrant` in Secret's namespace (or move Secret) |
| 4 | `404 Not Found` from NGINX even though route is accepted | Request path not matched by route rules | Use the correct path or expand route matches |
| 5 | `500 Internal Server Error` from NGINX | `backendRef.port` doesn't match Service port (`BackendNotFound`) | Fix backend port in HTTPRoute to match Service |
Useful references:
* [Gateway API concepts (kubernetes.io)](https://kubernetes.io/docs/concepts/services-networking/gateway/)
* [NGINX Gateway for Kubernetes (NGINX Gateway Fabric)](https://docs.nginx.com/nginx-ingress-controller/)
***
## Scenario 1 — Gateway exists but shows no address / Programmed = Unknown
Symptom: After applying a Gateway manifest the `ADDRESS` field is empty and `PROGRAMMED` remains `Unknown`.
Inspect the files and object:
```bash theme={null}
~/coding/kubernetes/nginx-fabric-gateway/kodekloud/lab-4-troubleshooting/tshoot-1
› ls
gateway.yaml
› kubectl get gateway
NAME CLASS ADDRESS PROGRAMMED AGE
gateway ngin Unknown 83s
```
Check GatewayClass and controller status:
```bash theme={null}
› kubectl get gatewayclasses
NAME CONTROLLER ACCEPTED AGE
nginx gateway.nginx.org/nginx-gateway-controller True 3h32m
```
Root cause: the Gateway is referencing the wrong class name (`ngin`) so the controller does not adopt or program it.
Fix: update `gateway.yaml` to use the correct `spec.gatewayClassName` (e.g. `nginx`) and reapply:
```bash theme={null}
› kubectl apply -f gateway.yaml
gateway.gateway.networking.k8s.io/gateway configured
```
Verify the Gateway is now programmed and has an address:
```bash theme={null}
› kubectl get gateway
NAME CLASS ADDRESS PROGRAMMED AGE
gateway nginx 10.96.31.67 True 2m30s
```
***
## Scenario 2 — HTTPRoute applied but Gateway shows "Attached Routes: 0"
Symptom: An HTTPRoute exists, but the Gateway's listener shows `Attached Routes: 0`.
Check the route:
```bash theme={null}
› kubectl get httproute
NAME HOSTNAMES AGE
coffee ["cafe.example.com"] 99s
```
Describe the Gateway (note `Attached Routes: 0`):
```bash theme={null}
› kubectl describe gateway gateway
# (excerpt)
Listeners:
Attached Routes: 0
```
Describe the HTTPRoute to inspect `parentRefs` and status:
```bash theme={null}
› kubectl describe httproute coffee
Name: coffee
Namespace: default
Spec:
Hostnames:
cafe.example.com
Parent Refs:
Group: gateway.networking.k8s.io
Kind: Gateway
Name: gatew
Section Name: http
Status: # empty / missing detailed status when parent not found
(no parents info)
```
Root cause: a typo in `parentRefs.name` (`gatew` instead of `gateway`) — the controller cannot associate the HTTPRoute with the Gateway, so attachment and parent status are missing.
Fix: correct `parentRefs.name` in `coffee-route.yaml` to the Gateway name (`gateway`) and reapply:
```bash theme={null}
# edit coffee-route.yaml to fix parentRefs.name: gateway
› kubectl apply -f coffee-route.yaml
httproute.gateway.networking.k8s.io/coffee configured
```
Verify status now includes parent conditions and the Gateway shows the attached route:
```bash theme={null}
› kubectl describe httproute coffee
# (excerpt)
Status:
Parents:
Conditions:
Type: Accepted
Status: True
Message: The Route is accepted
Conditions:
Type: ResolvedRefs
Status: True
Message: All references are resolved
Controller Name: gateway.nginx.org/nginx-gateway-controller
Parent Ref:
Name: gateway
Section Name: http
```
```bash theme={null}
› kubectl describe gateway gateway
# (excerpt)
Listeners:
Attached Routes: 1
Conditions:
Type: Accepted
Status: True
Message: The Listener is accepted
```
***
## Scenario 3 — TLS: Gateway can't access Secret in another namespace (ReferenceGrant needed)
Symptom: Gateway's HTTPS listener fails to resolve the TLS secret and shows:
```text theme={null}
Certificate ref to secret certificate/cafe-secret not permitted by any ReferenceGrant
```
Inspect namespaces, Secrets and Gateway:
```bash theme={null}
› kubectl get ns
NAME STATUS AGE
certificate Active 68s
default Active 7h11m
› kubectl get secrets -n certificate
NAME TYPE DATA AGE
cafe-secret kubernetes.io/tls 2 75s
› kubectl get gateway
NAME CLASS ADDRESS PROGRAMMED AGE
gateway nginx 10.96.205.15 True 81s
```
Describe the Gateway to see TLS certificate reference and the error:
```bash theme={null}
› kubectl describe gateway gateway
# (excerpt)
Listeners:
Name: https
Port: 443
Protocol: HTTPS
Tls:
Certificate Refs:
Kind: Secret
Name: cafe-secret
Namespace: certificate
Mode: Terminate
Conditions:
Type: ResolvedRefs
Status: False
Message: Certificate ref to secret certificate/cafe-secret not permitted by any ReferenceGrant
Reason: RefNotPermitted
```
Root cause: Gateways in the `default` namespace cannot reference a Secret in the `certificate` namespace by default. The Gateway API requires an explicit `ReferenceGrant` in the Secret's namespace to allow cross-namespace references.
Fix: Create a `ReferenceGrant` in the Secret namespace (`certificate`) that allows the Gateway to reference the Secret. Example manifest (`ref-grant.yaml`):
```yaml theme={null}
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
name: access-certificate
namespace: certificate
spec:
to:
- group: ""
kind: Secret
name: cafe-secret
from:
- group: gateway.networking.k8s.io
kind: Gateway
namespace: default
```
Apply it:
```bash theme={null}
› kubectl apply -f ref-grant.yaml
referencegrant.gateway.networking.k8s.io/access-certificate created
```
Verify the Gateway listener conditions are resolved and programmed:
```bash theme={null}
› kubectl describe gateway gateway
# (excerpt)
Listeners:
Conditions:
Type: ResolvedRefs
Status: True
Message: All references are resolved
Type: Programmed
Status: True
Message: The Listener is programmed
```
Note: alternatively, place the TLS `Secret` in the same namespace as the Gateway to avoid needing a `ReferenceGrant`. When cross-namespace references are required, `ReferenceGrant` is the recommended approach.
***
## Scenario 4 — 404 Not Found: route exists but you requested the wrong path
Symptom: Gateway and HTTPRoute are accepted, but client requests return `404 Not Found`.
Verify Service and Pods:
```bash theme={null}
› kubectl get svc
NAME TYPE CLUSTER-IP PORT(S)
coffee ClusterIP 10.96.197.88 80/TCP
gateway-nginx NodePort 10.96.205.15 80:31437/TCP
kubernetes ClusterIP 10.96.0.1 443/TCP
› kubectl get pod
NAME READY STATUS RESTARTS AGE
coffee-5b9c74f9d9-9rf2f 1/1 Running 0 6h54m
gateway-nginx-5f9d4c4ff-zbk45 1/1 Running 0 52s
```
Inspect the HTTPRoute manifest:
```yaml theme={null}
# coffee-route.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: coffee
spec:
parentRefs:
- name: gateway
sectionName: http
hostnames:
- "cafe.example.com"
rules:
- matches:
- path:
type: PathPrefix
value: /coffee
backendRefs:
- name: coffee
port: 80
```
The client requested a different path (`/tea`):
```bash theme={null}
› curl --resolve cafe.example.com:8080:127.0.0.1 \
http://cafe.example.com:8080/tea --include
HTTP/1.1 404 Not Found
Server: nginx
...
```
Root cause: The route only matches `PathPrefix /coffee`. Requests to `/tea` do not match and return 404.
Fix options:
* Use the correct path: request `/coffee`.
* Or update the HTTPRoute to include additional `matches` for `/tea` or a broader prefix.
Example correct request:
```bash theme={null}
› curl --resolve cafe.example.com:8080:127.0.0.1 \
http://cafe.example.com:8080/coffee --include
HTTP/1.1 200 OK
Server: nginx
...
URI: /coffee
Request ID: a7109559ef3e306fc5d0b65727ec43e0
```
***
## Scenario 5 — 500 Internal Server Error: backend port mismatch (BackendNotFound)
Symptom: The HTTPRoute is attached and accepted, but requests return `500 Internal Server Error`.
Reproduce the symptom:
```bash theme={null}
› kubectl get gateway
NAME CLASS ADDRESS PROGRAMMED AGE
gateway nginx 10.96.12.59 True 75s
› kubectl get httproute
NAME HOSTNAMES AGE
coffee ["cafe.example.com"] 75s
› curl --resolve cafe.example.com:8080:127.0.0.1 http://cafe.example.com:8080/coffee --include
HTTP/1.1 500 Internal Server Error
Server: nginx
...
```
Describe the HTTPRoute and inspect backend references:
```bash theme={null}
› kubectl describe httproute coffee
# (excerpt)
Rules:
Backend Refs:
Name: coffee
Port: 808
Status:
Parents:
Conditions:
Type: ResolvedRefs
Status: False
Message: No matching port for Service coffee and port 808
Reason: BackendNotFound
```
Check the Service ports:
```bash theme={null}
› kubectl get svc coffee -o wide
NAME TYPE CLUSTER-IP PORT(S)
coffee ClusterIP 10.96.197.88 80/TCP
```
Root cause: the HTTPRoute references port `808`, but the Service exposes port `80`. The controller cannot resolve the backend port, so NGINX cannot forward traffic and returns a 500.
Fix: update the HTTPRoute `backendRefs.port` to match the Service port `80`. Example before/after:
Before (incorrect):
```yaml theme={null}
# incorrect: backendRefs.port: 808
rules:
- matches:
- path:
type: PathPrefix
value: /coffee
backendRefs:
- name: coffee
port: 808
```
After (fixed):
```yaml theme={null}
# corrected: backendRefs.port: 80
rules:
- matches:
- path:
type: PathPrefix
value: /coffee
backendRefs:
- name: coffee
port: 80
```
Apply and verify:
```bash theme={null}
› kubectl apply -f coffee-route.yaml
httproute.gateway.networking.k8s.io/coffee configured
› kubectl describe httproute coffee
# (excerpt)
Status:
Parents:
Conditions:
Type: ResolvedRefs
Status: True
Message: All references are resolved
```
Request should now succeed:
```bash theme={null}
› curl --resolve cafe.example.com:8080:127.0.0.1 \
http://cafe.example.com:8080/coffee --include
HTTP/1.1 200 OK
Server: nginx
...
URI: /coffee
Request ID: 5b9e772af3cc2168626d1f29ab51abcd
```
***
When troubleshooting Gateway API resources, start with status fields and controller messages — they are purposefully descriptive. Typical culprits are incorrect `GatewayClass` names, typos in `parentRefs`, missing `ReferenceGrant` for cross-namespace Secrets, mismatched service ports, or incorrect route paths. Isolate whether the issue is control plane (controller not adopting), data plane (NGINX config/backends), or client-side (wrong hostname/path), then fix manifests or permissions and reapply.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.