Skip to main content
API7.ai Logo

Common Issues and Solutions

When issues arise while working with the Ingress Controller, the gateway and controller logs are usually the best place to start, as they often reveal the underlying issue quickly.

This document covers common issues you may encounter and provides practical guidance to troubleshoot and resolve them efficiently.

GatewayProxy Missing or Misconfigured​

GatewayProxy defines the provider connection used when a Gateway or IngressClass references it. If your resources are not being synchronized to the gateway, a common cause is that the referenced GatewayProxy is missing or incorrectly configured.

Verify that the GatewayProxy resource exists:

kubectl get gatewayproxy --all-namespaces

If GatewayProxy exists, review the GatewayProxy configuration:

kubectl describe gatewayproxy <gatewayproxy-name> -n <namespace>

For a Gateway, the referenced GatewayProxy must be in the same namespace. An IngressClass can specify the GatewayProxy namespace in spec.parameters. Confirm the provider Service or endpoints and any referenced authentication Secret. These checks do not prove provider connectivity; if the references are correct, continue with configuration synchronization troubleshooting.

IngressClassName Missing or Unspecified​

The following resources are processed when their ingressClassName selects a matching IngressClass or, if the field is omitted, a matching default IngressClass exists:

  • Ingress
  • ApisixRoute
  • ApisixUpstream
  • ApisixTls
  • ApisixPluginConfig
  • ApisixGlobalRule
  • ApisixConsumer

If an explicit ingressClassName is incorrect, or the field is omitted and no matching default exists, the resource will not be synchronized to the gateway.

ingress annotation

For Ingress resources, the controller first checks spec.ingressClassName, then falls back to the kubernetes.io/ingress.class annotation. If neither is set, the controller can use a matching default IngressClass.

Verify which IngressClass resources (cluster-scoped) exist:

kubectl get ingressclass

Review the IngressClass configuration to ensure it references the intended Ingress Controller:

kubectl describe ingressclass <ingressclass-name>

Verify that your resources have specified the correct ingressClassName, for instance:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80

etcd Failures​

This section applies only to APISIX deployments that use etcd as the configuration backend. If etcd pods repeatedly restart (CrashLoopBackOff) or remain unhealthy, APISIX configuration operations can fail.

Inspect the etcd pod status, events, and logs, then restore storage access and healthy cluster membership before continuing to troubleshoot the Ingress Controller. This is an APISIX gateway-backend issue, not an Ingress Controller failure, and does not apply to APISIX standalone mode.

Route Priority across Resources​

A higher value indicates a higher route priority. When multiple resource types are used together (Ingress, HTTPRoute, and ApisixRoute), routing behavior may be affected by differences in how route priorities are assigned and evaluated.

The following explains how priority is handled for each resource type:

  • Ingress: The native resource does not provide an explicit route priority. The controller sets one only when an HTTPRoutePolicy supplies it.
  • HTTPRoute: The controller calculates a deterministic priority from the route matching criteria unless an HTTPRoutePolicy sets one.
  • ApisixRoute: Allows explicit configuration of route priority.

Do not rely on a fixed ApisixRoute value to override every HTTPRoute or Ingress. Compare any priorities set through HTTPRoutePolicy and see Configure Route Priority and Matching Conditions.

HTTPRoute Filter and PluginConfig​

When both HTTPRoute filters and PluginConfig CRDs are applied to the same route, you may experience unexpected plugin behavior. Understanding how these interact helps avoid configuration conflicts.

The Ingress Controller maps built-in Gateway API HTTPRoute filters to specific plugins:

Do not configure the same underlying plugin through both a standard filter and PluginConfig on one rule. Overlapping entries are not merged reliably and can prevent the route from being translated. See HTTP Route Filters for the supported mappings.

Gateway API Routes Return 404 with Listener-Port Matching​

Gateway API HTTPRoute or GRPCRoute resources may return 404 when listener-port matching is enabled. TCPRoute and UDPRoute connections may also fail to match a stream route. These failures occur when Gateway listener ports do not match the ports that the gateway actually listens on.

Follow View the Rendered Controller Configuration to check the effective listener_port_match_mode in config.yaml. Helm charts render this field explicitly, so the installed value can differ from the controller's omitted-field default.

When listener-port matching injects a server_port route variable, the data plane evaluates it against its physical listening port, such as 9080, 9443, or a configured stream port. If the Gateway listener uses a different Service-facing port, the route does not match as intended. See the configuration reference for the mode triggers and product differences.

To resolve the issue, use one of the following approaches:

  • Set listener_port_match_mode to "off" to disable server_port route-var injection.
  • Configure the gateway to listen on the same ports declared in the Gateway listeners. For TCPRoute and UDPRoute, the listener port must equal the corresponding stream_proxy port.