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.

HTTPRoute Not Accepted? Debug Gateway API From Hostname to Pod

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, not status.conditions. The HTTPRoute CRD’s printer columns are only Hostnames and Age, so the default kubectl get output never shows acceptance.
  • Accepted=False is a Gateway-side refusal: the listener does not allow routes from your namespace, no listener hostname intersects yours, or your sectionName or port matches no listener.
  • ResolvedRefs=False is a backend problem: the Service does not exist, the kind is wrong, or a cross-namespace backend has no ReferenceGrant.
  • No status.parents entry at all usually means no controller considered the route: the parentRefs name or namespace is wrong, or the GatewayClass is not accepted.
  • Accepted and still failing? Check the Gateway’s Programmed condition, 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 (allowedRoutes default, 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 ↗
Prefer a text version?Read this page as Markdown · All pages