microsoft/aspire · error · ArgumentException

Path must start with '/'.

Error message

Path must start with '/'.

What it means

Kubernetes Ingress path rules must begin with '/' per the Ingress spec. Aspire's WithPath extension on a Kubernetes ingress resource validates the path before adding it to the resource's Paths collection and throws this ArgumentException for paths without the leading slash.

Solutions

1. Prefix the path with '/', e.g. '/api/v1'.
2. If building paths dynamically, ensure segments are joined with a leading '/'.
3. Leave the path as the Ingress-specified absolute form; Kubernetes does not support relative paths.
4. If you intended regex or ExactPrefix path types, the path still must start with '/'.

Example fix

// before
ingress.WithPath("api/v1");
// after
ingress.WithPath("/api/v1");

if (string.IsNullOrEmpty(path) || !path.StartsWith('/'))
    throw new ArgumentException("Ingress path must start with '/'");

try { ingress.WithPath(path); }
catch (ArgumentException ex) when (ex.Message == "Path must start with '/'.")
{ logger.LogError(ex, "Ingress path '{Path}' must be absolute", path); }

When it happens

Trigger: Calling the host-less WithPath overload on a Kubernetes ingress with a path like 'api' or 'api/v1' (no leading '/'), or an empty-after-normalization string that passes ThrowIfNullOrEmpty but fails the slash check.

Common situations: Copy-pasting route templates from frameworks that omit the leading slash; building paths dynamically with string concatenation that dropped the separator; confusing Ingress paths with relative URL paths in client code.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Aspire skills bundle contains an empty relative path.
• Aspire skills bundle path
• ASPIRERADIUS046
• ASPIRERADIUS061
• ASPIRERADIUS067

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

Appendix: source

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

    /// <code>
    /// var api = builder.AddProject&lt;MyApi&gt;("api");
    /// ingress.WithPath("/api", api.GetEndpoint("http"));
    /// </code>
    /// </example>
    [AspireExport("withIngressPath")]
    public static IResourceBuilder<KubernetesIngressResource> WithPath(
        this IResourceBuilder<KubernetesIngressResource> builder,
        string path,
        EndpointReference endpoint,
        IngressPathType pathType = IngressPathType.Prefix)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentException.ThrowIfNullOrEmpty(path);
        ArgumentNullException.ThrowIfNull(endpoint);

        if (!path.StartsWith('/'))
        {
            throw new ArgumentException("Path must start with '/'.", nameof(path));
        }

        builder.Resource.Paths.Add(new IngressPathConfig(
            Host: null,
            Path: path,
            PathType: pathType,
            Endpoint: endpoint));

        return builder;
    }

    /// <summary>
    /// Adds a host-scoped path rule to the ingress. The rule matches traffic for the
    /// specified host and path, forwarding it to the given endpoint's backing Kubernetes service.
    /// </summary>
    /// <param name="builder">The ingress resource builder.</param>
    /// <param name="host">The hostname to match (e.g., <c>"api.example.com"</c>).</param>
    /// <param name="path">The URL path to match (e.g., <c>"/"</c> or <c>"/api"</c>). Must start with <c>/</c>.</param>

View on GitHub (pinned to 25830f84bd)