dotnet/yarp · error · ArgumentException

Unknown transform: {string.Join(';', rawTransform.Keys)}

Error message

Unknown transform: {string.Join(';', rawTransform.Keys)}

What it means

Thrown by TransformBuilder.Build when no registered transform factory recognizes a raw transform entry. The builder iterates all `_factories`; if none returns true from `factory.Build(context, rawTransform)`, the entry's keys are joined and reported as unknown. Indicates a typo, an unsupported transform, or a missing transform extension.

Source

Thrown at src/ReverseProxy/Transforms/Builder/TransformBuilder.cs:129

        };

        if (rawTransforms?.Count > 0)
        {
            foreach (var rawTransform in rawTransforms)
            {
                var handled = false;
                foreach (var factory in _factories)
                {
                    if (factory.Build(context, rawTransform))
                    {
                        handled = true;
                        break;
                    }
                }

                if (!handled)
                {
                    throw new ArgumentException($"Unknown transform: {string.Join(';', rawTransform.Keys)}");
                }
            }
        }

        // Let the app add any more transforms it wants.
        foreach (var transformProvider in _providers)
        {
            transformProvider.Apply(context);
        }

        return CreateTransformer(context);
    }

    public HttpTransformer Create(Action<TransformBuilderContext> action)
    {
        return CreateInternal(action);
    }

View on GitHub (pinned to bd11867bee)

Solutions

1. Check the transform key spelling against the YARP transforms documentation (e.g. `PathRemovePrefix`, `RequestHeader`, `XForwarded`).
2. If it's a custom transform, register its factory with `builder.AddTransforms<MyFactory>()` or `AddTransform(context => ...)` before config is loaded.
3. Ensure any transform-extension package (e.g. session-affinity transforms) is referenced.
4. Compare the reported keys in the error against the keys your factory expects.

Example fix

// before
{ "Transforms": [ { "PathSetPrefx": "/api" } ] }
// after
{ "Transforms": [ { "PathRemovePrefix": "/api" } ] }

var knownKeys = new HashSet<string>(StringComparer.OrdinalIgnoreCase) { "PathRemovePrefix", "PathSet", "RequestHeader", /* ... */ };
if (!knownKeys.Overlaps(rawTransform.Keys)) throw new ArgumentException($"Unknown transform: {string.Join(';', rawTransform.Keys)}");

static bool IsKnownTransform(IReadOnlyDictionary<string,string> raw, ITransformFactory[] factories) =>
    factories.Any(f => f.Build(new TransformBuilderContext(), raw));

When it happens

Trigger: Route config contains a transforms entry whose keys do not match any registered transform factory (e.g. misspelled `PathSetFromAppService`, a custom transform name not registered, or an unknown shorthand key).

Common situations: Typo in transform key. Using a transform that requires a NuGet package/extension not referenced. Custom transform factory not added via `AddTransforms<TFactory>()`. YARP version mismatch where a transform was renamed.

Related errors

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

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