dotnet/yarp · error · ArgumentException

A non-empty CustomTransform value is required

Error message

A non-empty CustomTransform value is required

What it means

Thrown by the MyTransformFactory sample (ITransformFactory.Build) when a transform dictionary contains the key "CustomTransform" but its value is null or empty. This sample transform attaches the value as an HttpRequestOptionsKey on proxied requests and requires a non-empty payload. It is illustrative sample code showing how to enforce transform-value validation at build time.

Source

Thrown at samples/ReverseProxy.Transforms.Sample/MyTransformFactory.cs:34

            if (transformValues.TryGetValue("CustomTransform", out var value))
            {
                if (string.IsNullOrEmpty(value))
                {
                    context.Errors.Add(new ArgumentException("A non-empty CustomTransform value is required"));
                }

                return true; // Matched
            }
            return false;
        }

        public bool Build(TransformBuilderContext context, IReadOnlyDictionary<string, string> transformValues)
        {
            if (transformValues.TryGetValue("CustomTransform", out var value))
            {
                if (string.IsNullOrEmpty(value))
                {
                    throw new ArgumentException("A non-empty CustomTransform value is required");
                }

                context.AddRequestTransform(transformContext =>
                {
                    transformContext.ProxyRequest.Options.Set(new HttpRequestOptionsKey<string>("CustomTransform"), value);
                    return default;
                });

                return true;
            }

            return false;
        }
    }
}

View on GitHub (pinned to bd11867bee)

Solutions

1. Provide a non-empty value for the CustomTransform key in the route's Transforms config.
2. Remove the CustomTransform entry entirely if the transform is not needed for that route.
3. Register the MyTransformFactory with AddTransforms<MyTransformFactory>() so the sample recognizes the key.

Example fix

// before — appsettings.json
"Transforms": [ { "CustomTransform": "" } ]
// after
"Transforms": [ { "CustomTransform": "my-value" } ]

if (transformValues.TryGetValue("CustomTransform", out var v) && string.IsNullOrEmpty(v))
{
    // surface a config validation error at startup instead of letting Build throw
    context.Errors.Add(new ArgumentException("A non-empty CustomTransform value is required"));
}

static bool IsValidCustomTransformValue(string? v) => !string.IsNullOrWhiteSpace(v);

try { factory.Build(context, transformValues); }
catch (ArgumentException ex) when (ex.Message.Contains("CustomTransform"))
{ logger.LogWarning(ex, "Skipping transform due to empty value"); }

When it happens

Trigger: A route's Transforms collection includes an entry like { "CustomTransform": "" } or { "CustomTransform": null } in appsettings.json or programmatic config. Build is invoked during proxy pipeline construction when the route is activated.

Common situations: Configuring a transform block with an empty value by mistake. Copy-pasting a transform template and forgetting to fill in the value. YAML/JSON key present but value omitted.

Related errors

• A non-empty CustomMetadata value is required
• A non-empty CustomMetadata value is required
• Configuration Filter Error: Substitution for '{lookup}' in c
• Unable to load or apply the proxy configuration.
• The proxy config is invalid.

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