What causes "Path must start with '/'." in microsoft/aspire?

Prefix the path with '/' when calling WithRoute

microsoft/aspire · error · ArgumentException

Path must start with '/'.

Error message

Path must start with '/'.

What it means

The hostless overload of WithRoute validates that the route path is a valid HTTP path. Kubernetes Gateway API path matches must be absolute paths beginning with '/', so the extension throws ArgumentException for anything else.

Solutions

Prefix the path with '/' when calling WithRoute
Validate user-supplied route paths before passing them in

Example fix

// before
gateway.WithRoute("api", endpoint);
// after
gateway.WithRoute("/api", endpoint);

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try { gateway.WithRoute(path, endpoint); }
catch (ArgumentException ex) when (ex.ParamName == "path")
{ logger.LogError(ex, "Route path must be an absolute path starting with '/'."); }

Prevention

Always write route paths as absolute ('/api', not 'api')
Validate paths when loading route config from external sources
Add a small helper that normalizes paths before calling WithRoute

When it happens

Trigger: Calling WithRoute("api", endpoint, ...) with a path that does not start with '/', e.g. "api" or "api/users".

Common situations: Typos omitting the leading slash; paths copied from relative route tables; constructing the path string dynamically and missing the prefix.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Kubernetes/KubernetesGatewayExtensions.cs:116

    /// <param name="path">The URL path to match (e.g., <c>"/"</c> or <c>"/api"</c>). Must start with <c>/</c>.</param>
    /// <param name="endpoint">The endpoint reference identifying the target service and port.</param>
    /// <param name="pathType">The path matching strategy. Defaults to <see cref="GatewayPathMatchType.PathPrefix"/>.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{KubernetesGatewayResource}"/> for chaining.</returns>
    /// <ats-returns>The resource builder.</ats-returns>
    [AspireExport("withGatewayPathRoute")]
    public static IResourceBuilder<KubernetesGatewayResource> WithRoute(
        this IResourceBuilder<KubernetesGatewayResource> builder,
        string path,
        EndpointReference endpoint,
        GatewayPathMatchType pathType = GatewayPathMatchType.PathPrefix)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentException.ThrowIfNullOrEmpty(path);
        ArgumentNullException.ThrowIfNull(endpoint);

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

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

        return builder;
    }

    /// <summary>
    /// Adds a host-and-path-based routing rule to the gateway. The rule matches traffic for
    /// the specified host and path, routing it to the given endpoint's backing Kubernetes service.
    /// This generates an <c>HTTPRoute</c> resource with a <c>hostnames</c> filter.
    /// </summary>
    /// <param name="builder">The gateway resource builder.</param>
    /// <param name="host">The hostname to match (e.g., <c>"api.example.com"</c>).</param>

View on GitHub (pinned to 25830f84bd)