microsoft/aspire · error · ArgumentException

The apiPath must contain only URL-safe path characters…

Error message

The apiPath must contain only URL-safe path characters (alphanumeric, '/', '-', '_'). Invalid character: '{c}'

What it means

ValidateApiPath enforces that the apiPath argument to AddNextJsApp contains only ASCII letters, digits, '/', '-', and '_', because it becomes part of a URL route and is embedded in generated configuration. Any other character (spaces, dots, query chars, Unicode) throws an ArgumentException naming the offending character.

Solutions

Rewrite the apiPath using only letters, digits, '/', '-', and '_' (e.g. "/api/v1-data").
Percent-encode or remove special characters; move query parameters out of the path.
Trim whitespace from the path before passing it.

Example fix

// before
builder.AddNextJsApp("web", "./web", options => options.ApiPath = "/api/v1.0");
// after
builder.AddNextJsApp("web", "./web", options => options.ApiPath = "/api/v1-0");

Defensive patterns

Strategy: validation

Validate before calling

static bool IsSafeApiPath(string? path) =>
    !string.IsNullOrEmpty(path) && path.All(c => char.IsAsciiLetterOrDigit(c) || c is '/' or '-' or '_');

Type guard

bool IsSafeApiPath(string? path) => !string.IsNullOrEmpty(path) && path.All(c => char.IsAsciiLetterOrDigit(c) || c is '/' or '-' or '_');

Try / catch

try { builder.AddNextJsApp("web", "./web", o => o.ApiPath = apiPath); } catch (ArgumentException ex) when (ex.Message.Contains("URL-safe")) { /* sanitize apiPath */ }

Prevention

Sanitize user/team-supplied paths with a whitelist regex before use.
Never embed query strings, dots, or spaces in ApiPath.
Add unit tests for path validation in your build pipeline.

When it happens

Trigger: Passing an apiPath containing characters outside [A-Za-z0-9/-_], e.g. "/api/v1.0", "api data", "/api?x=1", or a Unicode-containing path.

Common situations: Including version dots or query strings in the API path; trailing/leading whitespace; copy-pasted paths with encoded characters (%20) or Windows separators (\).

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.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.JavaScript/JavaScriptHostingExtensions.cs:3199

            {
                // If we can't read the config, skip the check — the Docker build will surface the error.
            }

            return;
        }

        throw new InvalidOperationException(
            "No Next.js configuration file found. AddNextJsApp expects one of: " +
            string.Join(", ", s_nextConfigFileNames));
    }

    private static void ValidateApiPath(string apiPath)
    {
        foreach (var c in apiPath)
        {
            if (!char.IsAsciiLetterOrDigit(c) && c is not '/' and not '-' and not '_')
            {
                throw new ArgumentException($"The apiPath must contain only URL-safe path characters (alphanumeric, '/', '-', '_'). Invalid character: '{c}'", nameof(apiPath));
            }
        }
    }

    /// <summary>
    /// Walks up from <paramref name="startDirectory"/> to find the nearest <c>node_modules</c> directory.
    /// </summary>
    private static string? FindNearestNodeModules(string startDirectory)
    {
        var current = Path.GetFullPath(startDirectory);
        while (current is not null)
        {
            var candidate = Path.Join(current, "node_modules");
            if (Directory.Exists(candidate))
            {
                return candidate;
            }

View on GitHub (pinned to 25830f84bd)