microsoft/aspire · error · ArgumentOutOfRangeException

Unknown path type.

Error message

Unknown path type.

What it means

ToKubernetesString converts an IngressPathType enum value to the Kubernetes ingress pathType string. The library throws this ArgumentOutOfRangeException when the enum value is not one of the three defined members (Prefix, Exact, ImplementationSpecific). This guards against an enum value added in a newer Aspire version or a cast from an arbitrary int that has no Kubernetes representation.

Solutions

  1. Use only IngressPathType.Prefix, IngressPathType.Exact, or IngressPathType.ImplementationSpecific when configuring ingress paths.
  2. When reading path type values from config or external input, validate them against Enum.IsDefined<IngressPathType>(value) before casting/using.
  3. Update the Aspire.Hosting.Kubernetes package to a version consistent with the code defining the enum value being passed.

Example fix

// before
var pathType = (IngressPathType)int.Parse(config["pathType"]);
// after
var raw = int.Parse(config["pathType"]);
if (!Enum.IsDefined(typeof(IngressPathType), raw))
{
    throw new ArgumentException($"Unsupported ingress pathType: {raw}");
}
var pathType = (IngressPathType)raw;
Defensive patterns

Strategy: validation

Validate before calling

if (!Enum.IsDefined(typeof(IngressPathType), pathType))
{
    throw new ArgumentException($"Unsupported IngressPathType: {pathType}", nameof(pathType));
}

Type guard

static bool IsKnownPathType(IngressPathType value) =>
    value is IngressPathType.Prefix or IngressPathType.Exact or IngressPathType.ImplementationSpecific;

Try / catch

try
{
    var s = KubernetesIngressExtensions.ToKubernetesString(pathType);
}
catch (ArgumentOutOfRangeException ex)
{
    // ex.ParamName == "pathType"; log and fall back to "ImplementationSpecific"
}

Prevention

When it happens

Trigger: Calling ToKubernetesString with an IngressPathType value outside the three defined members, typically via an unchecked cast like (IngressPathType)99, or when code compiled against a newer enum member runs against this switch that does not handle it.

Common situations: Persisting or deserializing ingress path type configuration from user config files or environment values where an integer was cast blindly to the enum; mixing package versions where one defines an extra IngressPathType member.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Kubernetes/KubernetesIngressExtensions.cs:388

        ArgumentNullException.ThrowIfNull(builder);
        ArgumentException.ThrowIfNullOrEmpty(key);
        ArgumentNullException.ThrowIfNull(value);

        builder.Resource.IngressAnnotations[key] = ReferenceExpression.Create($"{value.Resource}");
        return builder;
    }

    /// <summary>
    /// Converts an <see cref="IngressPathType"/> enum value to the Kubernetes API string representation.
    /// </summary>
    internal static string ToKubernetesString(this IngressPathType pathType)
    {
        return pathType switch
        {
            IngressPathType.Prefix => "Prefix",
            IngressPathType.Exact => "Exact",
            IngressPathType.ImplementationSpecific => "ImplementationSpecific",
            _ => throw new ArgumentOutOfRangeException(nameof(pathType), pathType, "Unknown path type.")
        };
    }
}

View on GitHub (pinned to 25830f84bd)