microsoft/aspire · error · ArgumentException

apiTarget is required when apiPath is specified.

Error message

apiTarget is required when apiPath is specified.

What it means

Aspire's JavaScript hosting throws this when you specify an apiPath (the route prefix under which the API proxy is mounted) but omit the corresponding apiTarget (the resource the path proxies to). The two options are intentionally paired; the library cannot guess the target resource, so it fails fast at builder time.

Solutions

  1. Pass apiTarget together with apiPath, e.g. .WithApiProxy(apiPath: "/api", apiTarget: apiResourceBuilder).
  2. If no API proxy is intended, remove apiPath entirely instead of passing it without a target.
  3. Null-check the resource builder variable before the call so a missing target surfaces earlier with a clearer message.

Example fix

// before
builder.AddViteApp("frontend", "./frontend")
    .WithApiProxy(apiPath: "/api");
// after
builder.AddViteApp("frontend", "./frontend")
    .WithApiProxy(apiPath: "/api", apiTarget: apiProjectBuilder);
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

bool HasCompleteProxyOptions(string? apiPath, IResourceBuilder<IResource>? apiTarget) =>
    string.IsNullOrEmpty(apiPath) ? apiTarget is null : apiTarget is not null;

Try / catch

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

Prevention

When it happens

Trigger: Calling the API-proxy configuration (e.g. WithApiProxy-style extension on AddViteApp/AddNpmApp results) with apiPath set but apiTarget null, e.g. .WithApiProxy(apiPath: "/api").

Common situations: Copy-pasting a sample and deleting the IResourceBuilder argument; the target resource builder variable being null at the call site; migrating from an API that previously inferred the target.

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/d7104317e50a12c8. Report an issue: GitHub.

Appendix: source

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

            TargetEndpointName = targetEndpointName
        };
        return PublishAsStaticWebsiteCore(builder, apiPath, apiTarget, options);
    }

    [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)
            {

View on GitHub (pinned to 25830f84bd)