dotnet/yarp · error · ArgumentException

Unexpected value for Forwarded: {token}. Expected 'for', 'ho

Error message

Unexpected value for Forwarded: {token}. Expected 'for', 'host', 'proto', or 'by'

What it means

Thrown by ForwardedTransformFactory when parsing the `Forwarded` transform's spec list and encountering a token that is not `for`, `host`, `proto`, or `by` (case-insensitive). The Forwarded transform (RFC 7239) only emits those four fields, so any other token is invalid.

Source

Thrown at src/ReverseProxy/Transforms/ForwardedTransformFactory.cs:222

                    useFor = true;
                    forFormat = NodeFormat.Random; // RFC Default
                }
                else if (string.Equals(token, ByKey, StringComparison.OrdinalIgnoreCase))
                {
                    useBy = true;
                    byFormat = NodeFormat.Random; // RFC Default
                }
                else if (string.Equals(token, HostKey, StringComparison.OrdinalIgnoreCase))
                {
                    useHost = true;
                }
                else if (string.Equals(token, ProtoKey, StringComparison.OrdinalIgnoreCase))
                {
                    useProto = true;
                }
                else
                {
                    throw new ArgumentException($"Unexpected value for Forwarded: {token}. Expected 'for', 'host', 'proto', or 'by'");
                }
            }

            var expected = 1;

            var headerAction = ForwardedTransformActions.Set;
            if (transformValues.TryGetValue(ActionKey, out headerValue))
            {
                expected++;
                headerAction = Enum.Parse<ForwardedTransformActions>(headerValue);
            }

            if (useFor && transformValues.TryGetValue(ForFormatKey, out var forFormatString))
            {
                expected++;
                forFormat = Enum.Parse<NodeFormat>(forFormatString, ignoreCase: true);
            }

View on GitHub (pinned to bd11867bee)

Solutions

1. Use only the supported tokens: `for`, `host`, `proto`, `by` (case-insensitive, comma-separated).
2. If you need a custom field, use a custom RequestHeader transform instead.
3. Re-read the Forwarded transform docs and align the spec string.

Example fix

// before
{ "Forwarded": "fro,host" }
// after
{ "Forwarded": "for,host,proto" }

var allowed = new[] { "for", "host", "proto", "by" };
foreach (var token in spec.Split(','))
    if (!allowed.Contains(token, StringComparer.OrdinalIgnoreCase)) throw new ArgumentException($"Bad Forwarded token: {token}");

static bool IsValidForwardedSpec(string spec) =>
    spec.Split(',').All(t => new[]{"for","host","proto","by"}.Contains(t.Trim(), StringComparer.OrdinalIgnoreCase));

When it happens

Trigger: Config sets the Forwarded transform with an unknown field token, e.g. `Forwarded: user,for` or a typo like `fro` instead of `for`.

Common situations: Confusing the RFC 7239 Forwarded fields with X-Forwarded-* field names. Typo in a token. Copying an example that used a non-standard extension.

Related errors

• Unknown transform: {string.Join(';', rawTransform.Keys)}
• The transform contains more parameters than expected: {strin
• {string.Join(";", transformValues.Keys)}
• 'headerName' cannot be null or empty.
• 'headerName' cannot be null or empty.

AI-assisted analysis of dotnet/yarp@bd11867bee (2026-08-13). Data as JSON: /api/errors/3bb37544a3297676. Report an issue: GitHub.