dotnet/yarp · error · ArgumentException

A non-empty CustomMetadata value is required

Error message

A non-empty CustomMetadata value is required

What it means

Thrown by the MyTransformProvider sample (ITransformProvider.Apply) when route or cluster Metadata contains the key "CustomMetadata" with a null or empty value. Unlike the validation-phase methods (which add to context.Errors), Apply throws directly because it cannot construct the request transform without a value. This is sample code demonstrating metadata-driven transforms.

Source

Thrown at samples/ReverseProxy.Transforms.Sample/MyTransformProvider.cs:45

            // Check all clusters for a custom property and validate the associated transform data.
            if (context.Cluster.Metadata?.TryGetValue("CustomMetadata", out var value) ?? false)
            {
                if (string.IsNullOrEmpty(value))
                {
                    context.Errors.Add(new ArgumentException("A non-empty CustomMetadata value is required"));
                }
            }
        }

        public void Apply(TransformBuilderContext transformBuildContext)
        {
            // Check all routes for a custom property and add the associated transform.
            if ((transformBuildContext.Route.Metadata?.TryGetValue("CustomMetadata", out var value) ?? false)
                || (transformBuildContext.Cluster?.Metadata?.TryGetValue("CustomMetadata", out value) ?? false))
            {
                if (string.IsNullOrEmpty(value))
                {
                    throw new ArgumentException("A non-empty CustomMetadata value is required");
                }

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

View on GitHub (pinned to bd11867bee)

Solutions

1. Set a non-empty value for CustomMetadata in the route or cluster Metadata dictionary.
2. Remove the CustomMetadata metadata key if the transform is not intended for that route/cluster.
3. Ensure ValidateRoute/ValidateCluster (which also flag this) catch the problem at startup before Apply throws at request time.

Example fix

// before — appsettings.json route metadata
"Metadata": { "CustomMetadata": "" }
// after
"Metadata": { "CustomMetadata": "some-value" }

if ((route.Metadata?.TryGetValue("CustomMetadata", out var v) ?? false) && string.IsNullOrEmpty(v))
{
    context.Errors.Add(new ArgumentException("A non-empty CustomMetadata value is required"));
}

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

try { provider.Apply(transformBuildContext); }
catch (ArgumentException ex) when (ex.Message.Contains("CustomMetadata"))
{ logger.LogWarning(ex, "Skipping metadata transform"); }

When it happens

Trigger: A RouteConfig.Metadata or ClusterConfig.Metadata dictionary has an entry "CustomMetadata" mapped to "" or null. Apply runs during the transform-building phase when the proxy pipeline is assembled for the route/cluster.

Common situations: Metadata key added in config but value left empty. Migrating from a transform-values approach to a metadata approach and forgetting to populate the value.

Related errors

• A non-empty CustomTransform 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/6f499fb837e146a0. Report an issue: GitHub.