[github-actions]

agentgateway/agentgateway#4097 — filters: better error handling

Docs versions: standalone/main, kubernetes/main

No code-path rule covers 2 touched file(s). The planner could route these only by identifier search, so the candidate pages may miss what they changed, including in the other mode:

• crates/agentgateway/src/http/filters.rs
• crates/core/src/serdes.rs

What changes for users: Standalone configuration validation now rejects several invalid filter configurations before startup: invalid header modifier names or values, direct response policies that set both body and bodyExpression, request mirror percentages outside 0.0 to 1.0, and invalid redirect or rewrite paths.

What the docs now say: The standalone Header manipulation, Direct Response, Mirroring, Redirects, and Rewrites pages now state the validation rules beside the fields that readers configure.

Not verified: No cluster and no local agentgateway binary were available in this sandbox; the configuration is unrun.

How agentgateway-4097 was drafted, and what was not verified

• Code PR: filters: better error handling agentgateway#4097
• Code issue: none linked
• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main and kubernetes/main, documented in the development tree where unreleased changes go.
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Document the standalone filter validation behavior on the page that owns each affected policy.
• Learned: The planner targets were broad, but the code diff and the target checkout showed specific standalone policy pages for header manipulation, direct responses, request mirroring, redirects, and rewrites.
• Did: Updated those five standalone policy pages and wrote a proposed standalone release-note entry.

Why a documentation change is necessary

The pull request moves several filter errors from request time to standalone configuration validation. The existing policy pages showed the affected fields without the constraints that now make a configuration fail before startup. Readers who copy those examples and adjust the fields need the rejection conditions on the same pages.

What changed on disk

• content/docs/standalone/main/documentation/configuration/traffic-management/manipulation.md — Notes that standalone validation rejects invalid HTTP header names or values in header modifiers.
• content/docs/standalone/main/documentation/configuration/traffic-management/direct-response.md — Notes that body and bodyExpression are mutually exclusive.
• content/docs/standalone/main/documentation/configuration/resiliency/mirroring.md — Documents the valid requestMirror.percentage range.
• content/docs/standalone/main/documentation/configuration/traffic-management/redirects.md — Documents redirect path validation and the path.prefix route-match requirement.
• content/docs/standalone/main/documentation/configuration/traffic-management/rewrites.md — Documents rewrite path validation and the path.prefix route-match requirement.

How to verify this change

1. In a standalone configuration, set requestMirror.percentage: 1.2 and run agentgateway -f config.yaml --validate-only. The command should fail with requestMirror percentage must be between 0.0 and 1.0, got 1.2.
2. In a direct response policy, set both body and bodyExpression, then run agentgateway -f config.yaml --validate-only. The command should fail with directResponse body and bodyExpression may not both be set.
3. In a redirect or rewrite policy, set path.prefix on a route whose match is not pathPrefix, then run agentgateway -f config.yaml --validate-only. The command should fail with path prefix rewrite requires every match to be a path prefix match.

What was not verified

The configuration was not applied to a cluster, and standalone validation was not run with an agentgateway binary. Every command in this diff is unrun.

How the pages were chosen (triage report)

Draft a documentation change

agentgateway/agentgateway#4097 — filters: better error handling

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main, kubernetes/main
• Summary (read from the body): Capture more errors at serde time, rejecting the config up front for local standalone cases
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 2 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • crates/agentgateway/src/http/filters.rs
  • crates/core/src/serdes.rs

A declared version this draft does not reach

This pull request is planned for more than one documentation version,
and nothing in the diff publishes to:

• kubernetes/main

A file under assets/ reaches a version tree only where a page in that
tree reuses it, so editing a shared asset does not by itself cover every
mode a product ships. Either that version still needs writing, or the
change genuinely does not apply there and the reason belongs in this body.

Release notes

This pull request also adds its release-note entries:

• content/docs/standalone/main/release-notes/release-notes.md: filters: better error handling (fix, under Traffic management)

Release notes kept out of a tree. Check that each change really does not reach the trees named here:

• filters: better error handling agentgateway#4097: not placed for kubernetes/main, because its note's versions: line. If the change also reaches that tree, add the note there.

Draft branch: pr-tracker-draft-agentgateway-4097

---

Important

The test suite has not run on this pull request. It was opened by github-actions[bot], and GitHub does not start workflows for pull requests opened with the repository's own token. Doc tests, link checking and the static checks are held as action_required until somebody presses Approve and run on the Checks tab. Cloudflare Pages and DCO are GitHub Apps rather than Actions, so those two do run on their own.

Please approve the checks before reviewing the content: an absence of failures here means the tests have not run, not that they passed.

[cloudflare-workers-and-pages]

Deploying agentproxy with    Cloudflare Pages

Latest commit:	150edd1
Status:	✅  Deploy successful!
Preview URL:	https://3b265863.agentproxy.pages.dev
Branch Preview URL:	https://pr-tracker-draft-agentgatewa-43lu.agentproxy.pages.dev

View logs