{"record":{"id":"3b5d969905723a13","repo":"microsoft/aspire","slug":"path-must-start-with","errorCode":null,"errorMessage":"Path must start with '/'.","messagePattern":"Path must start with '/'\\.","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Kubernetes/KubernetesGatewayExtensions.cs","lineNumber":116,"sourceCode":"    /// <param name=\"path\">The URL path to match (e.g., <c>\"/\"</c> or <c>\"/api\"</c>). Must start with <c>/</c>.</param>\n    /// <param name=\"endpoint\">The endpoint reference identifying the target service and port.</param>\n    /// <param name=\"pathType\">The path matching strategy. Defaults to <see cref=\"GatewayPathMatchType.PathPrefix\"/>.</param>\n    /// <returns>A reference to the <see cref=\"IResourceBuilder{KubernetesGatewayResource}\"/> for chaining.</returns>\n    /// <ats-returns>The resource builder.</ats-returns>\n    [AspireExport(\"withGatewayPathRoute\")]\n    public static IResourceBuilder<KubernetesGatewayResource> WithRoute(\n        this IResourceBuilder<KubernetesGatewayResource> builder,\n        string path,\n        EndpointReference endpoint,\n        GatewayPathMatchType pathType = GatewayPathMatchType.PathPrefix)\n    {\n        ArgumentNullException.ThrowIfNull(builder);\n        ArgumentException.ThrowIfNullOrEmpty(path);\n        ArgumentNullException.ThrowIfNull(endpoint);\n\n        if (!path.StartsWith('/'))\n        {\n            throw new ArgumentException(\"Path must start with '/'.\", nameof(path));\n        }\n\n        builder.Resource.Routes.Add(new GatewayRouteConfig(\n            Host: null,\n            Path: path,\n            PathType: pathType,\n            Endpoint: endpoint));\n\n        return builder;\n    }\n\n    /// <summary>\n    /// Adds a host-and-path-based routing rule to the gateway. The rule matches traffic for\n    /// the specified host and path, routing it to the given endpoint's backing Kubernetes service.\n    /// This generates an <c>HTTPRoute</c> resource with a <c>hostnames</c> filter.\n    /// </summary>\n    /// <param name=\"builder\">The gateway resource builder.</param>\n    /// <param name=\"host\">The hostname to match (e.g., <c>\"api.example.com\"</c>).</param>","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Kubernetes/KubernetesGatewayExtensions.cs#L98-L134","documentation":"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.","triggerScenarios":"Calling WithRoute(\"api\", endpoint, ...) with a path that does not start with '/', e.g. \"api\" or \"api/users\".","commonSituations":"Typos omitting the leading slash; paths copied from relative route tables; constructing the path string dynamically and missing the prefix.","solutions":["Prefix the path with '/' when calling WithRoute","Validate user-supplied route paths before passing them in"],"exampleFix":"// before\ngateway.WithRoute(\"api\", endpoint);\n// after\ngateway.WithRoute(\"/api\", endpoint);","handlingStrategy":"validation","validationCode":"if (string.IsNullOrEmpty(path) || !path.StartsWith('/'))\n    throw new ArgumentException(\"Path must start with '/'.\", nameof(path));","typeGuard":null,"tryCatchPattern":"try { gateway.WithRoute(path, endpoint); }\ncatch (ArgumentException ex) when (ex.ParamName == \"path\")\n{ logger.LogError(ex, \"Route path must be an absolute path starting with '/'.\"); }","preventionTips":["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"],"tags":["kubernetes","gateway-api","validation","argument"],"backgroundTag":"invalid-argument-format","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}