Help Center/ Cloud Container Engine/ User Guide/ Networking/ Gateway API/ Locating Gateway or HTTPRoute Exceptions
Updated on 2026-08-13 GMT+08:00
View PDF
Share

Locating Gateway or HTTPRoute Exceptions

If you encounter exceptions when using Envoy Gateway to manage Gateways and HTTPRoutes, such as routes not taking effect or abnormal traffic, follow the instructions in this section to troubleshoot.

Diagnosing Gateway Exceptions

  • If the Gateway resource is in the Not ready state or the associated workload is abnormal, see the table below.

    Exception Information

    Cause

    Troubleshooting

    No addresses have been assigned to the Gateway

    Abnormal Service associated with the Gateway
    1. Check the Service associated with the Gateway.
    2. Run kubectl describe svc <service-name> to check for abnormal events.

    Envoy replicas unavailable

    Envoy workload exceptions
    1. Check the status of the Envoy workload and its pods.
    2. Check the logs of the related pod or use kubectl describe pod to view abnormal events.
  • If the status of the Gateway resource is Invalid, perform the following steps:
    1. Check the GatewayClass associated with the Gateway. 
      kubectl get gateway <gateway-name> -n <namespace> -o jsonpath='{.spec.gatewayClassName}'

      Replace <gateway-name> and <namespace> with the name and namespace of the invalid Gateway.

      Example output:

      envoy-gateway
    2. Check the controller name of the GatewayClass. 
      kubectl get gatewayclass <gateway-class-name> -o jsonpath='{.spec.controllerName}'

      <gateway-class-name> is the gatewayClassName obtained in the previous step.

      Example output:

      gateway.envoyproxy.io/gatewayclass-controller
    3. Check the result and perform follow-up operations.
      • If the result is gateway.envoyproxy.io/gatewayclass-controller, the binding is correct. Proceed to check whether Envoy Gateway is running properly.
      • If the output does not contain this name, the GatewayClass is not managed by Envoy Gateway. Modify spec.gatewayClassName of the Gateway resource and bind it again.

Diagnosing HTTPRoute Exceptions

If the Parents bound to an HTTPRoute is abnormal, the route definition may not match the Gateway or the backend Service may be unreachable. See the table below.

Exception Information

Cause

Troubleshooting

No listeners match this parent ref

The Gateway referenced by parentRef does not have any matching listener.
  1. Check whether a port is specified in the HTTPRoute.
  2. Check whether the port matches the listener port configured in the Gateway.

There were no hostname intersections between the HTTPRoute and this parent ref's Listener(s).

The hostname of the HTTPRoute does not match the hostname specified in the Gateway listener.
  1. Check the hostnames field of the HTTPRoute.
  2. Ensure that the value of this field overlaps with the hostname of the Gateway listener (or matches a wildcard).

No listeners included by this parent ref allowed this attachment.

The namespace where the HTTPRoute is located is not allowed to be mounted by the Gateway listener.
  1. Check the listeners[].allowedRoutes.namespaces configuration of the Gateway.
  2. Check whether the namespace where the HTTPRoute resides is within the allowed range (for example, From: All or a specific selector is specified).

Failed to process route rule 0 backendRef 0: service default/backeneeeed not found

The target backend Service configured in the HTTPRoute does not exist.
  1. Check whether the Service name and namespace corresponding to backendRefs configured in the HTTPRoute are correct.
  2. Ensure that the Service has been successfully created in the cluster and the port configuration is correct.

The associated Gateway does not exist or is invalid.

The associated Gateway does not exist or is invalid.

Associate the HTTPRoute with an existing Gateway or check why the Gateway is invalid.
Parent Topic: Gateway API