ENGINEERING NOTES / KUBERNETES
HTTPRoute Not Accepted? Debug Gateway API From Hostname to Pod
Why an HTTPRoute is not accepted, where Gateway API writes the reason, and a seven-step kubectl check from DNS to pod readiness, with v1.7.0 reason codes.

When an HTTPRoute is not accepted, the Gateway controller writes the reason into the route’s status.parents[].conditions, one entry per parent Gateway, and kubectl get httproute does not show it. Read the Accepted and ResolvedRefs conditions for each parent first: the reason code (for example NotAllowedByListeners or NoMatchingListenerHostname) names the fix. If the route is accepted and the hostname still fails, walk the rest of the chain in order: DNS, Gateway, TLS, Service, endpoints, pods.
Below you’ll find that order, the commands for each step, and a table of every route reason code in the Gateway API v1.7.0 source. We make Berth, a self-hosted Kubernetes dashboard that checks part of this chain for you. We say exactly which parts it checks and which it doesn’t.
The short answer
- Look in the right place. Route status lives under
status.parents, notstatus.conditions. The HTTPRoute CRD’s printer columns are onlyHostnamesandAge, so the defaultkubectl getoutput never shows acceptance. Accepted=Falseis a Gateway-side refusal: the listener does not allow routes from your namespace, no listener hostname intersects yours, or yoursectionNameorportmatches no listener.ResolvedRefs=Falseis a backend problem: the Service does not exist, the kind is wrong, or a cross-namespace backend has no ReferenceGrant.- No
status.parentsentry at all usually means no controller considered the route: theparentRefsname or namespace is wrong, or the GatewayClass is not accepted. - Accepted and still failing? Check the Gateway’s
Programmedcondition, the TLS certificate, and whether the Service has ready endpoints.
Why doesn’t kubectl get httproute show the problem?
Because the HTTPRoute CRD only defines two printer columns. In the v1.7.0 source (apis/v1/httproute_types.go, lines 28 and 29) they are Hostnames (.spec.hostnames) and Age. A rejected route and a working one print the same row.
The status you need is a list of RouteParentStatus entries, one per parent the controller evaluated. Each entry carries the parentRef, the controllerName that wrote it, and its own conditions. Print them like this:
kubectl get httproute app -n shop -o jsonpath='{range .status.parents[*]}{.parentRef.namespace}/{.parentRef.name} {.parentRef.sectionName} by {.controllerName}{"\n"}{range .conditions[*]} {.type}={.status} {.reason}: {.message}{"\n"}{end}{end}'
Or, if you have jq:
kubectl get httproute app -n shop -o json \
| jq '.status.parents[] | {parent: .parentRef, conditions: [.conditions[] | {type, status, reason, message}]}'
We checked these field paths against the v1.7.0 types. We did not run the commands on a live cluster for this post, because no kind or k3d install was available, so treat the exact output format as indicative.
What does each HTTPRoute reason code mean?
Each reason code points at one fix. The table lists the route reasons the Gateway API source defines. The “meaning” column paraphrases the comment on each constant in apis/v1/shared_types.go at v1.7.0. Controllers may use other reasons, but the spec asks them to prefer these.
| Condition | Reason | What it means | Usual fix |
|---|---|---|---|
| Accepted=False | NotAllowedByListeners |
No listener’s allowedRoutes permits this route |
Allow the route’s namespace on the listener (see below) |
| Accepted=False | NoMatchingListenerHostname |
No compatible listener hostname intersects the route’s hostnames | Fix spec.hostnames or the listener hostname |
| Accepted=False | NoMatchingParent |
The sectionName or port in parentRefs matches no listener |
Use the listener’s exact name, or drop sectionName |
| Accepted=False | UnsupportedValue |
An enum value is not recognised by this implementation | Check the controller’s supported features |
| Accepted=False | IncompatibleFilters |
A rule combines filters that cannot coexist, such as URLRewrite and RequestRedirect |
Split the rule |
| Accepted=Unknown | Pending |
The controller has not reconciled the route yet | Check the controller is running and watching this namespace |
| ResolvedRefs=False | BackendNotFound |
A backendRef points at a resource that does not exist |
Fix the Service name or namespace |
| ResolvedRefs=False | RefNotPermitted |
A backendRef crosses namespaces without a ReferenceGrant |
Add a ReferenceGrant in the backend’s namespace |
| ResolvedRefs=False | InvalidKind |
A backendRef has an unknown or unsupported group or kind |
Use kind: Service (the default) or a kind your controller supports |
| ResolvedRefs=False | UnsupportedProtocol |
The backend’s app protocol is not supported | Check the Service port’s appProtocol |
There is also PartiallyInvalid, which is only ever True: some rules are valid and some are not. The spec lets the controller either drop the invalid rules (message starts with “Dropped Rule”) or keep the last good version of the route (message starts with “Fall Back”), and in both cases Accepted stays True. So an accepted route can still be serving an older configuration than the one you applied.
A ResolvedRefs=False route can be accepted and partly serve traffic. The spec is explicit about what happens to the broken share: requests “that would have otherwise been routed to an invalid backend” must get a 500, and for a Service with no ready endpoints implementations “SHOULD return a 503”. With two equally weighted backends and one invalid, about half your requests fail.
The chain, in order
Work from the outside in. Each step assumes the one before it passed.
1. Does the hostname resolve to the Gateway?
kubectl get gateway -A # ADDRESS and PROGRAMMED columns
dig +short app.example.com
The Gateway CRD prints Class, Address, Programmed and Age. If dig returns something other than the Gateway’s address, traffic never reaches your route. If you use external-dns, check its logs for the hostname.
2. Is the Gateway programmed, and does a listener take your route?
kubectl get gatewayclass # ACCEPTED must be True
kubectl get gateway public -n infra -o jsonpath='{range .status.listeners[*]}{.name}{" attachedRoutes="}{.attachedRoutes}{" "}{range .conditions[*]}{.type}={.status}({.reason}) {end}{"\n"}{end}'
Programmed=False on the Gateway has defined reasons: Invalid, Pending, NoResources and AddressNotAssigned. The per-listener attachedRoutes count tells you whether your route attached to the listener you expected. A route without sectionName attaches to every listener that admits it, which is why one route often shows on both the http and https listeners.
3. Does the listener allow routes from your namespace?
This is the most common cause of NotAllowedByListeners. A listener’s allowedRoutes.namespaces.from defaults to Same (apis/v1/gateway_types.go, line 955 at v1.7.0), so a shared Gateway in infra rejects routes from shop until you say otherwise:
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: public
namespace: infra
spec:
gatewayClassName: example
listeners:
- name: https
protocol: HTTPS
port: 443
hostname: "*.example.com"
tls:
certificateRefs:
- name: wildcard-example-com
allowedRoutes:
namespaces:
from: Selector
selector:
matchLabels:
gateway-access: public
Then label the namespace: kubectl label namespace shop gateway-access=public. from: All also works, but a selector keeps the decision explicit.
4. Do the hostnames intersect?
If both the listener and the route set hostnames, at least one must match, or the route is not accepted. Gateway API treats a listener wildcard as a suffix match: the spec says *.example.com “would match both test.example.com, and foo.test.example.com, but not example.com”.
That rule is wider than the TLS rule. A certificate for *.example.com covers only one label: RFC 9525, section 6.3, says a wildcard “can only match one label”. So foo.test.example.com can attach to a *.example.com listener and still fail the TLS handshake. If you serve two-level names, put them on their own listener and certificate.
5. Is the certificate ready?
kubectl get secret wildcard-example-com -n infra
kubectl get certificate -n infra # if you use cert-manager: READY must be True
A missing Secret usually shows on the listener as ResolvedRefs=False with InvalidCertificateRef. A Secret in another namespace needs a ReferenceGrant, the same as a backend.
6. Do the backend references resolve?
For a Service in a different namespace from the route, the backend’s namespace must grant the reference:
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
name: allow-shop-routes
namespace: payments # the Service's namespace
spec:
from:
- group: gateway.networking.k8s.io
kind: HTTPRoute
namespace: shop # the route's namespace
to:
- group: ""
kind: Service
Without it, the route reports ResolvedRefs=False with RefNotPermitted.
7. Are there ready endpoints behind the Service?
kubectl get endpointslices -n shop -l kubernetes.io/service-name=app \
-o jsonpath='{range .items[*].endpoints[*]}{.addresses[0]} ready={.conditions.ready}{"\n"}{end}'
kubectl get pods -n shop -l app=app
No ready endpoints means the selector matches no pods, or the pods fail their readiness probe. Also check that the route’s backendRefs[].port is the Service port, not the container port.
What does kubectl check, and what does a dashboard check?
We built the comparison below from Berth’s source at tag v0.5.1 (26 October 2026, the current release), file backend/k8s/overview.go. Berth names the first broken link for each exposed hostname, using four checks in a fixed order. On 8 November 2026 we ran the classification function unchanged in a scratch test against hand-built inputs. These are the exact strings it returns:
no route references the gateway -> status=down reason="No HTTPRoute attached"
gateway not programmed -> status=down reason="Gateway not programmed"
https, cert not ready -> status=degraded reason="TLS certificate not ready"
no ready backends -> status=degraded reason="No backend pods ready"
| Step | kubectl | Berth v0.5.1 |
|---|---|---|
| DNS points at the Gateway | dig |
Shows the Gateway address DNS should point at; does not resolve DNS itself |
Gateway Programmed |
Yes | Yes |
| Route attached to the Gateway | Read status.parents |
Matches parentRefs to the Gateway by name and namespace (spec only) |
Route Accepted and ResolvedRefs reasons |
Yes | No. It does not read status.parents, so a route rejected by allowedRoutes still counts as attached |
| Listener wildcard matching | Controller decides | Treats *. as one label, so a two-level host under a wildcard listener is not listed |
| TLS certificate | Secret and cert-manager | cert-manager Certificate Ready, matched by Secret or DNS name |
| Ready endpoints | EndpointSlices | EndpointSlices, per backend Service |
Two of those rows are gaps, and you should hear that from us. For a “not accepted” route, Berth points you at the Gateway or the backends, but the reason code is only in kubectl. What Berth does well is the opposite view: one list of every exposed hostname across namespaces, with the first broken link named, so you notice the broken one before a user does.
Why this matters more in 2026
Best-effort maintenance of Ingress NGINX was due to end in March 2026, and the Kubernetes project’s retirement notice recommends Gateway API as one migration path. Teams moving over often meet the shared-Gateway pattern for the first time: the platform team owns one Gateway in one namespace, and app teams own routes in others. That split is where allowedRoutes, ReferenceGrants and hostname intersection bite, because the YAML that fixes your route lives in somebody else’s namespace.
If you are still choosing a dashboard after the Kubernetes Dashboard archive, our comparison of what to use in 2026 covers the field, and how Berth’s read-only assistant works explains the AI side. The Berth product page lists every guide in this series.
FAQ
Why does my HTTPRoute show no status at all?
No controller wrote a status.parents entry. Check that parentRefs names the right Gateway and namespace, and that the GatewayClass shows ACCEPTED=True.
What is the most common cause of NotAllowedByListeners?
The listener’s allowedRoutes.namespaces.from defaults to Same, so a Gateway in another namespace rejects your route until you allow it (step 3).
Can a route be accepted and still return errors?
Yes. Accepted=True with ResolvedRefs=False still serves traffic to the valid backends. The share sent to an invalid backend gets a 500, and a Service with no ready endpoints should get a 503.
Does a wildcard listener cover foo.test.example.com?
For route attachment, yes: Gateway API treats the wildcard as a suffix match. A *.example.com certificate covers only one label, so the TLS handshake can still fail (step 4).
Sources
Checked on 8 November 2026:
- Gateway API v1.7.0 source:
apis/v1/shared_types.go(route conditions and reasons,BackendRef.weight),apis/v1/httproute_types.go(hostname intersection, 500 and 503 rules, printer columns),apis/v1/gateway_types.go(allowedRoutesdefault, Gateway and listener conditions), at github.com/kubernetes-sigs/gateway-api - RFC 9525, section 6.3, on wildcard certificates
- Ingress NGINX retirement, Kubernetes blog, 11 November 2025
- Berth v0.5.1 source:
backend/k8s/overview.go(classifyEndpoint,hostMatches),backend/k8s/describe.go,backend/k8s/objects.go
Try it on your cluster
Berth is a restricted beta for trusted administrators on a single cluster. Viewing is free with no key, it runs as one container in your cluster, and it does not replace the kubectl steps above. If a single list of every hostname with its first broken link would save you time, install Berth.
SEE IT ON YOUR OWN CLUSTER
Berth: a Kubernetes dashboard
you run yourself.
Endpoint health, capacity planning, and a read-only AI SRE. Free for small clusters, license checked offline. Discuss your Kubernetes security and architecture with CloudGuys.
Get a free Community key ↗ Talk to CloudGuys ↗