What causes "Unknown gateway path match type '{route.PathType}'." in microsoft/aspire?

microsoft/aspire · error · InvalidOperationException

Unknown gateway path match type

Error message

Unknown gateway path match type '{route.PathType}'.

What it means

When emitting HTTPRoute matches, the route's PathType is mapped to a Gateway API path match type string. If route.PathType holds a value outside the GatewayPathMatchType enum (Exact, PathPrefix, RegularExpression), the switch falls through and throws. This is an internal invariant guard against an unmappable path match type.

Solutions

Use only GatewayPathMatchType.Exact, GatewayPathMatchType.PathPrefix, or GatewayPathMatchType.RegularExpression when calling WithRoute
Fix any deserialized configuration so it contains a valid enum value
Upgrade the library if a newly added enum member should be supported

Example fix

// before
route.WithRoute(path: "/x", endpoint: ep, pathType: (GatewayPathMatchType)99);
// after
route.WithRoute(path: "/x", endpoint: ep, pathType: GatewayPathMatchType.PathPrefix);

Defensive patterns

Strategy: validation

Validate before calling

if (!Enum.IsDefined(typeof(GatewayPathMatchType), pathType))
    throw new ArgumentOutOfRangeException(nameof(pathType), pathType, "Unknown path match type.");

Type guard

bool IsValidPathType(GatewayPathMatchType t) => t is GatewayPathMatchType.Exact or GatewayPathMatchType.PathPrefix or GatewayPathMatchType.RegularExpression;

Try / catch

try { route.WithRoute("/api", ep, pathType); }
catch (InvalidOperationException ex) when (ex.Message.StartsWith("Unknown gateway path match type"))
{ logger.LogError(ex, "Invalid GatewayPathMatchType value."); }

Prevention

Always pass GatewayPathMatchType members, never raw casts or unvalidated config values
When deserializing config, validate enum values with Enum.IsDefined
Re-check enum handling after library upgrades that may add members

When it happens

Trigger: A GatewayRouteConfig whose PathType is not one of the defined GatewayPathMatchType values, typically from a cast of an invalid int or a default struct value when the enum member was not set.

Common situations: Deserializing route configuration from JSON/config where an unknown or numeric enum value was used; a library version mismatch where a new enum member is not handled by the emitting code.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/9f287d4e0be523d8. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Kubernetes/KubernetesEnvironmentResource.cs:1212

            else
            {
                httpRoute.Spec.Hostnames.AddRange(resolvedHostnames);
            }

            foreach (var route in hostGroup)
            {
                var backendRef = ResolveGatewayBackendRef(route.Endpoint, deploymentTargets, gatewayResource.Name, logger);
                if (backendRef is null)
                {
                    continue;
                }

                var pathType = route.PathType switch
                {
                    GatewayPathMatchType.Exact => "Exact",
                    GatewayPathMatchType.PathPrefix => "PathPrefix",
                    GatewayPathMatchType.RegularExpression => "RegularExpression",
                    _ => throw new InvalidOperationException($"Unknown gateway path match type '{route.PathType}'.")
                };

                var rule = new HttpRouteRuleV1();
                rule.Matches.Add(new HttpRouteMatchV1
                {
                    Path = new HttpRoutePathMatchV1
                    {
                        Type = pathType,
                        Value = route.Path
                    }
                });
                rule.BackendRefs.Add(backendRef);
                httpRoute.Spec.Rules.Add(rule);
            }

            if (httpRoute.Spec.Rules.Count > 0)
            {
                gatewayResource.GeneratedHttpRoutes.Add(httpRoute);

View on GitHub (pinned to 25830f84bd)