microsoft/aspire · error · ArgumentNullException

ArgumentNullException for parameter 'prefix' (PathString…

Error message

ArgumentNullException for parameter 'prefix' (PathString value is null).

What it means

WithTransformPathPrefix requires a PathString with a non-null Value; a default PathString has null Value. The extension validates up front and throws ArgumentNullException for 'prefix' to surface the problem at the call site.

Solutions

Pass a non-empty prefix string such as "/api".
Prefer the string-based overload; the PathString overload is not available in polyglot app hosts anyway.
Coalesce null config values: var prefix = config["PathPrefix"] ?? "/api".
Validate the prefix with string.IsNullOrEmpty before constructing the PathString.

Example fix

// before
route.WithTransformPathPrefix(new PathString(prefixOrNull));
// after
route.WithTransformPathPrefix(prefixOrNull ?? "/prefix");

Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrEmpty(prefix.Value))
    throw new ArgumentException("prefix must be non-empty before calling WithTransformPathPrefix");

Type guard

static bool HasValue(PathString p) => !string.IsNullOrEmpty(p.Value);

Try / catch

try { route.WithTransformPathPrefix(prefix); }
catch (ArgumentNullException ex) when (ex.ParamName == "prefix") { /* skip transform or use default */ }

Prevention

Validate config-derived prefixes before use.
Use string overloads for transforms.
Skip adding transforms whose inputs are absent rather than passing null.

When it happens

Trigger: Calling WithTransformPathPrefix with default(PathString), new PathString(null), or a null string implicitly converted to PathString.

Common situations: Prefix read from nullable config/appsettings key that is absent; a variable initialized with default(PathString); null return from a helper that resolves the prefix.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Yarp/ConfigurationBuilder/Transforms/PathTransformExtensions.cs:57

    [AspireExport]
    internal static YarpRoute WithTransformPathSet(this YarpRoute route, string path)
    {
        ArgumentNullException.ThrowIfNull(route);
        ArgumentNullException.ThrowIfNull(path);

        return route.WithTransformPathSet(new PathString(path));
    }

    /// <summary>
    /// Adds the transform which will prefix the request path with the given value.
    /// </summary>
    /// <remarks>This overload is not available in polyglot app hosts. Use the string-based overload instead.</remarks>
    [AspireExportIgnore(Reason = "PathString is not ATS-compatible. Use the string-based overload instead.")]
    public static YarpRoute WithTransformPathPrefix(this YarpRoute route, PathString prefix)
    {
        if (prefix.Value is null)
        {
            throw new ArgumentNullException(nameof(prefix));
        }

        route.Configure(r => r.WithTransformPathPrefix(prefix));

        return route;
    }

    /// <summary>
    /// Adds the transform which will prefix the request path with the given value.
    /// </summary>
    /// <param name="route">The route to configure.</param>
    /// <param name="prefix">The path prefix to add.</param>
    /// <returns>The configured <see cref="YarpRoute"/>.</returns>
    [AspireExport]
    internal static YarpRoute WithTransformPathPrefix(this YarpRoute route, string prefix)
    {
        ArgumentNullException.ThrowIfNull(route);
        ArgumentNullException.ThrowIfNull(prefix);

View on GitHub (pinned to 25830f84bd)