dotnet/yarp · error · ArgumentException

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

Error message

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

What it means

Thrown by ResponseTransformFactory.Build when a 'ResponseHeader' transform key is present but neither 'Set' nor 'Append' is among the sibling keys. Uses ArgumentException with a descriptive message listing the actual keys. An optional 'When' key (Always/Success/Failure) may also be present. The Validate method reports the same condition non-throwing at config load.

Source

Thrown at src/ReverseProxy/Transforms/ResponseTransformFactory.cs:163

                TransformHelpers.CheckTooManyParameters(transformValues, expected: 3);
                condition = Enum.Parse<ResponseCondition>(whenValue, ignoreCase: true);
            }
            else
            {
                TransformHelpers.CheckTooManyParameters(transformValues, expected: 2);
            }

            if (transformValues.TryGetValue(SetKey, out var setValue))
            {
                context.AddResponseHeader(responseHeaderName, setValue, append: false, condition);
            }
            else if (transformValues.TryGetValue(AppendKey, out var appendValue))
            {
                context.AddResponseHeader(responseHeaderName, appendValue, append: true, condition);
            }
            else
            {
                throw new ArgumentException($"Unexpected parameters for ResponseHeader: {string.Join(';', transformValues.Keys)}. Expected 'Set' or 'Append'");
            }
        }
        else if (transformValues.TryGetValue(ResponseTrailerKey, out var responseTrailerName))
        {
            var condition = ResponseCondition.Success;
            if (transformValues.TryGetValue(WhenKey, out var whenValue))
            {
                TransformHelpers.CheckTooManyParameters(transformValues, expected: 3);
                condition = Enum.Parse<ResponseCondition>(whenValue, ignoreCase: true);
            }
            else
            {
                TransformHelpers.CheckTooManyParameters(transformValues, expected: 2);
            }

            if (transformValues.TryGetValue(SetKey, out var setValue))
            {
                context.AddResponseTrailer(responseTrailerName, setValue, append: false, condition);

View on GitHub (pinned to bd11867bee)

Solutions

1. Add 'Set' or 'Append' to the entry, e.g. { "ResponseHeader": "X-Foo", "Set": "bar" }.
2. Fix key-name typos — keys are case-sensitive.
3. Keep startup config validation enabled so this is reported at startup.
4. When building in code, assert Set or Append is present before calling Build.

Example fix

// before
{ "ResponseHeader": "X-Powered-By" }
// after
{ "ResponseHeader": "X-Powered-By", "Set": "YARP", "When": "Always" }

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

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

When it happens

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

Common situations: appsettings.json transform missing the Set/Append line; typo'd key (e.g. lowercase 'set'); a config-generated route emitting an incomplete transform object.

Related errors

• Unexpected parameters for RequestHeader: {string.Join(';', t
• {string.Join(";", transformValues.Keys)}
• 'headerName' cannot be null or empty.
• '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/18aeee9b7f1c6512. Report an issue: GitHub.