What causes "URL must be a string, Uri, or parameter resource builder." in microsoft/aspire?

Pass the URL as a string (e.g. "https://api.example.com") or a System.Uri instance.

microsoft/aspire · error · ArgumentException

URL must be a string, Uri, or parameter resource builder.

Error message

URL must be a string, Uri, or parameter resource builder.

What it means

The polyglot AddExternalService overload accepts only string, Uri, or IResourceBuilder<ParameterResource> for its url argument; any other object type falls through the switch and throws ArgumentException.

Solutions

Pass the URL as a string (e.g. "https://api.example.com") or a System.Uri instance.
Pass an IResourceBuilder<ParameterResource> when the URL should be parameterized.
Inspect the runtime type of the value you pass and convert it to string or Uri at the call site.

Example fix

// before
builder.AddExternalServiceForPolyglot("api", someObject);
// after
builder.AddExternalServiceForPolyglot("api", "https://api.example.com");

Defensive patterns

Strategy: type-guard

Validate before calling

if (url is not string and not Uri and not IResourceBuilder<ParameterResource>) throw new ArgumentException("url must be string, Uri, or parameter builder");

Type guard

static bool IsSupportedUrlArg(object? url) => url is string or Uri or IResourceBuilder<ParameterResource>;

Try / catch

try { AddExternalServiceForPolyglot(builder, name, url); } catch (ArgumentException ex) when (ex.Message.Contains("string, Uri")) { /* convert and retry */ }

Prevention

Normalize URL values to string/Uri at the boundary of polyglot host code
Document accepted url types in shared helper signatures
Cast explicitly rather than passing object

When it happens

Trigger: Calling the polyglot/non-generic AddExternalService with an unsupported url value type, e.g. a numeric, an IResourceBuilder of a different resource type, or null-typed boxed value from a scripting host.

Common situations: Polyglot AppHosts (F#, Python interop) passing the wrong type for url; marshalling issues where a parameter arrives as a non-matching type; forgetting that Uri and string are the only direct literal forms.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/ExternalServiceBuilderExtensions.cs:59

    /// <summary>
    /// Adds an external service resource
    /// </summary>
    [AspireExport("addExternalService")]
    internal static IResourceBuilder<ExternalServiceResource> AddExternalServiceForPolyglot(
        this IDistributedApplicationBuilder builder,
        [ResourceName] string name,
        [AspireUnion(typeof(string), typeof(Uri), typeof(IResourceBuilder<ParameterResource>))] object url)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(name);
        ArgumentNullException.ThrowIfNull(url);

        return url switch
        {
            string urlString => builder.AddExternalService(name, urlString),
            Uri uri => builder.AddExternalService(name, uri),
            IResourceBuilder<ParameterResource> urlParameter => builder.AddExternalService(name, urlParameter),
            _ => throw new ArgumentException("URL must be a string, Uri, or parameter resource builder.", nameof(url))
        };
    }

    /// <summary>
    /// Adds an external service resource to the distributed application with the specified URI.
    /// </summary>
    /// <param name="builder">The distributed application builder.</param>
    /// <param name="name">The name of the resource.</param>
    /// <param name="uri">The URI of the external service.</param>
    /// <returns>An <see cref="IResourceBuilder{ExternalServiceResource}"/> instance.</returns>
    [AspireExportIgnore(Reason = "Polyglot AppHosts use the internal addExternalService dispatcher export.")]
    public static IResourceBuilder<ExternalServiceResource> AddExternalService(this IDistributedApplicationBuilder builder, [ResourceName] string name, Uri uri)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(name);
        ArgumentNullException.ThrowIfNull(uri);

        return AddExternalServiceImpl(builder, name, uri);

View on GitHub (pinned to 25830f84bd)