microsoft/aspire · error · ArgumentException

apiPath is required when apiTarget is specified.

Error message

apiPath is required when apiTarget is specified.

What it means

Mirror case of the apiPath-without-target check: you supplied an apiTarget resource but no apiPath. Both are required because the library must know under which URL prefix to proxy requests to the target; it refuses to pick a default prefix implicitly.

Solutions

  1. Provide an explicit apiPath along with apiTarget, e.g. .WithApiProxy(apiPath: "/api", apiTarget: apiBuilder).
  2. If no proxying is needed, remove the apiTarget argument.
  3. Default the path at the call site (apiPath ??= "/api") only if a conventional prefix is acceptable in your app.

Example fix

// before
.WithApiProxy(apiTarget: apiBuilder);
// after
.WithApiProxy(apiPath: "/api", apiTarget: apiBuilder);
Defensive patterns

Strategy: validation

Validate before calling

if (apiTarget is not null && string.IsNullOrEmpty(apiPath))
    throw new ArgumentException("apiPath is required when apiTarget is specified.");

Try / catch

try { builder.WithApiProxy(apiPath, apiTarget); }
catch (ArgumentException ex) when (ex.ParamName == "apiPath")
{
    apiPath = "/api"; // or skip proxy configuration
}

Prevention

When it happens

Trigger: Calling the API-proxy extension with apiTarget set and apiPath null, e.g. .WithApiProxy(apiTarget: apiBuilder).

Common situations: Refactoring where the path was extracted into a variable that became null; copying only the target argument from docs; assuming a default "/api" path exists (it does not).

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

    [Experimental("ASPIREJAVASCRIPT001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
    private static IResourceBuilder<TResource> PublishAsStaticWebsiteCore<TResource>(
        IResourceBuilder<TResource> builder,
        string? apiPath,
        IResourceBuilder<IResourceWithServiceDiscovery>? apiTarget,
        PublishAsStaticWebsiteOptions options)
        where TResource : JavaScriptAppResource
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentException.ThrowIfNullOrEmpty(options.OutputPath);

        if (apiPath is not null && apiTarget is null)
        {
            throw new ArgumentException("apiTarget is required when apiPath is specified.", nameof(apiTarget));
        }

        if (apiTarget is not null && apiPath is null)
        {
            throw new ArgumentException("apiPath is required when apiTarget is specified.", nameof(apiPath));
        }

        if (apiPath is not null && apiTarget is not null)
        {
            if (!apiPath.StartsWith('/'))
            {
                throw new ArgumentException("The apiPath must start with '/'.", nameof(apiPath));
            }

            apiPath = apiPath.TrimEnd('/');

            if (apiPath.Length == 0)
            {
                throw new ArgumentException("The apiPath must not be '/' — it would match all requests and make the static site unreachable.", nameof(apiPath));
            }

            ValidateApiPath(apiPath);
            builder.WithReference(apiTarget);

View on GitHub (pinned to 25830f84bd)