dotnet/yarp · error · ArgumentException

Unexpected parameters for RequestHeader: {string.Join(';', t

Error message

Unexpected parameters for RequestHeader: {string.Join(';', transformValues.Keys)}. Expected 'Set' or 'Append'

What it means

Thrown by RequestHeadersTransformFactory.Build when a 'RequestHeader' transform key is present but neither 'Set' nor 'Append' is found among the sibling keys. Unlike the QueryTransformFactory equivalents (which throw NotSupportedException), this uses ArgumentException with a descriptive message naming the keys found. The Validate method reports the same condition non-throwing at config load time.

Source

Thrown at src/ReverseProxy/Transforms/RequestHeadersTransformFactory.cs:96

        else if (transformValues.TryGetValue(RequestHeaderOriginalHostKey, out var originalHost))
        {
            TransformHelpers.CheckTooManyParameters(transformValues, expected: 1);
            context.AddOriginalHost(bool.Parse(originalHost));
        }
        else if (transformValues.TryGetValue(RequestHeaderKey, out var headerName))
        {
            TransformHelpers.CheckTooManyParameters(transformValues, expected: 2);
            if (transformValues.TryGetValue(SetKey, out var setValue))
            {
                context.AddRequestHeader(headerName, setValue, append: false);
            }
            else if (transformValues.TryGetValue(AppendKey, out var appendValue))
            {
                context.AddRequestHeader(headerName, appendValue, append: true);
            }
            else
            {
                throw new ArgumentException($"Unexpected parameters for RequestHeader: {string.Join(';', transformValues.Keys)}. Expected 'Set' or 'Append'");
            }
        }
        else if (transformValues.TryGetValue(RequestHeaderRouteValueKey, out var headerNameFromRoute))
        {
            TransformHelpers.CheckTooManyParameters(transformValues, expected: 2);
            if (transformValues.TryGetValue(AppendKey, out var routeValueKeyAppend))
            {
                context.AddRequestHeaderRouteValue(headerNameFromRoute, routeValueKeyAppend, append: true);
            }
            else if (transformValues.TryGetValue(SetKey, out var routeValueKeySet))
            {
                context.AddRequestHeaderRouteValue(headerNameFromRoute, routeValueKeySet, append: false);
            }
            else
            {
                throw new NotSupportedException(string.Join(";", transformValues.Keys));
            }
        }

View on GitHub (pinned to bd11867bee)

Solutions

1. Add 'Set' or 'Append' to the transform entry, e.g. { "RequestHeader": "X-Foo", "Set": "bar" }.
2. Correct key-name typos — keys are case-sensitive ('Set', not 'set').
3. Keep startup config validation enabled so this is caught at startup, not at Build time.
4. When building in code, assert the dictionary contains Set or Append before calling Build.

Example fix

// before
{ "Transforms": [ { "RequestHeader": "X-Foo" } ] }
// after
{ "Transforms": [ { "RequestHeader": "X-Foo", "Append": "svc" } ] }

if (transformValues.ContainsKey("RequestHeader")
    && !transformValues.ContainsKey("Set")
    && !transformValues.ContainsKey("Append"))
{
    throw new InvalidOperationException(
        "RequestHeader transform requires 'Set' or 'Append'.");
}

static bool IsValidRequestHeaderTransform(IReadOnlyDictionary<string, string> t)
    => t.ContainsKey("RequestHeader")
       && (t.ContainsKey("Set") || t.ContainsKey("Append"));

When it happens

Trigger: A transform dictionary like { "RequestHeader": "X-Foo" } with no Set/Append. Reaches Build when config validation is bypassed/skipped or transforms are built programmatically via ITransformFactory.Build.

Common situations: appsettings.json transform object missing the Set/Append line; typo such as 'set' (lowercase); a config-database-driven route store emitting an incomplete transform.

Related errors

• {string.Join(";", transformValues.Keys)}
• Unexpected parameters for ResponseHeader: {string.Join(';',
• Unknown transform: {string.Join(';', rawTransform.Keys)}
• The transform contains more parameters than expected: {strin
• Unexpected value for Forwarded: {token}. Expected 'for', 'ho

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