microsoft/aspire · error · ArgumentException

The path must be a relative path.

Error message

The path must be a relative path.

What it means

This validator normalizes a path destined for the generated Dockerfile (a virtual container path) and requires it to be relative. A path starting with '/' (after optional drive/UNC stripping) cannot be placed under the container's app directory, so it throws an ArgumentException with the path parameter name.

Solutions

1. Pass a relative path without a leading slash, e.g. "dist" or "out/frontend".
2. Strip the leading '/' from the computed path before calling the API.
3. Do not attempt to point container paths at host absolute locations; mount/copy semantics differ.

Example fix

// before
options.OutputPath = "/app/dist";
// after
options.OutputPath = "dist";

static bool IsRelativeContainerPath(string? path) =>
    !string.IsNullOrEmpty(path) && !path.Replace("\\", "/").TrimStart().StartsWith('/');

bool IsRelativeContainerPath(string? path) => !string.IsNullOrEmpty(path) && !path.Replace("\\", "/").TrimStart().StartsWith('/');

try { options.OutputPath = p; } catch (ArgumentException ex) when (ex.Message.Contains("relative path")) { /* strip leading slash / recompute relative path */ }

When it happens

Trigger: Passing an absolute path such as "/app/dist", "/home/user/out", or a rooted Windows path that reduces to a leading slash as the path argument to AddNextJsApp-style path options (e.g. publish/dist directory settings).

Common situations: Reusing a host filesystem path in a container-path option; concatenating a base directory and forgetting to strip the leading '/'; confusion between host paths and container paths.

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

• The Next.js config file
• The path must not contain ".." segments.
• Container runtime ' ' was not found on PATH. Install or set…
• No Next.js configuration file found. AddNextJsApp expects…
• The apiPath must contain only URL-safe path characters…

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

Appendix: source

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

            }
            current = parent;
        }

        return null;
    }

    private static string NormalizeRelativePath(string path)
    {
        var normalizedPath = path.Replace('\\', '/');

        if (normalizedPath.StartsWith("./", StringComparison.Ordinal))
        {
            normalizedPath = normalizedPath[2..];
        }

        if (normalizedPath.StartsWith('/'))
        {
            throw new ArgumentException("The path must be a relative path.", nameof(path));
        }

        // Reject path traversal segments. These are virtual Docker container paths (not host
        // filesystem paths), so Path.GetFullPath cannot be used — it produces platform-specific
        // results (e.g. D:\app\dist on Windows). Segment-based validation works correctly
        // cross-platform for container paths.
        var segments = normalizedPath.Split('/', StringSplitOptions.RemoveEmptyEntries);
        foreach (var segment in segments)
        {
            if (segment == "..")
            {
                throw new ArgumentException("The path must not contain \"..\" segments.", nameof(path));
            }
        }

        return string.Join('/', segments);
    }

View on GitHub (pinned to 25830f84bd)