For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Monitor and troubleshoot proxy configuration rejections with metrics and events.

The agentgateway proxy validates XDS updates from the control plane before applying them. A rejected resource produces a NACK (negative acknowledgement).

The proxy retains its last known-good configuration for that resource. Traffic continues, but the rejected change is not applied.

The control plane counts rejections in agentgateway_xds_rejects_total on port 9092. The control plane also creates a Kubernetes Warning event on the affected Gateway.

Rejections can occur when the proxy cannot parse a value accepted by the Kubernetes API server and control plane. One example is an invalid agentRuntimeArn in an AgentgatewayBackend.

View the rejection metric

1. Port-forward the control plane deployment.

   kubectl port-forward -n agentgateway-system deployment/agentgateway 9092

2. Query the metrics endpoint and search for the rejection counter.

   curl http://localhost:9092/metrics | grep xds_rejects

   Example output when rejections have occurred:

   # HELP agentgateway_xds_rejects_total Total number of xDS responses rejected by agentgateway proxy
   # TYPE agentgateway_xds_rejects_total counter
   agentgateway_xds_rejects_total 3
   

You can use this metric to configure alerts in Prometheus that fire when rejections occur. For guidance on setting up the observability stack, see the OTel stack guide.

View rejection events

A rejection creates a Kubernetes Warning event on the Gateway with reason AgentGatewayNackError. The message is a JSON list with these fields:

• key: The rejected resource.
• error: The error from the proxy.

1. List rejection events in the namespace where your Gateway is deployed.

   kubectl get events -n agentgateway-system --field-selector=reason=AgentGatewayNackError

   Example output:

   LAST SEEN   TYPE      REASON                  OBJECT                       MESSAGE
   8s          Warning   AgentGatewayNackError   gateway/agentgateway-proxy   [{"key":"backend/agentgateway-system/agentcore","error":"error: invalid AgentCore ARN: not-an-arn"}]
   

2. View events on the Gateway resource directly.

   kubectl describe gateway agentgateway-proxy -n agentgateway-system

   Example output:

   Events:
     Type     Reason                 Age   From                           Message
     ----     ------                 ----  ----                           -------
     Warning  AgentGatewayNackError  13s   agentgateway.dev/agentgateway  [{"key":"backend/agentgateway-system/agentcore","error":"error: invalid AgentCore ARN: not-an-arn"}]