microsoft/aspire · error · InvalidOperationException

Optional references are not supported for Azure Functions…

Error message

Optional references are not supported for Azure Functions resources.

What it means

The Azure Functions resource extension's TryWithReference implements service-reference wiring for Functions projects, but only unconditional references are supported. Passing optional: true makes the method throw this InvalidOperationException because optional references would require config-dependent wiring that Functions resources do not support.

Solutions

Remove the optional flag and use the required WithReference overload for the Functions resource.
Conditionally call WithReference only when the referenced resource is actually available.
If the dependency may be absent, guard the call site and skip the reference instead of using optional references.

Example fix

// before
functionsProject.WithReference(redis, optional: true);

// after
functionsProject.WithReference(redis);

Defensive patterns

Strategy: validation

Validate before calling

bool supportsOptional = destination is not AzureFunctionsProjectResource;

Type guard

static bool SupportsOptionalReference(IResourceBuilder<IResource> b) => b.Resource is not AzureFunctionsProjectResource;

Try / catch

try { functionsProject.WithReference(dep, optional: true); } catch (InvalidOperationException ex) when (ex.Message.Contains("Optional references")) { /* fall back to required reference */ }

Prevention

Do not use optional:true overloads on Functions project resources.
Gate WithReference calls behind availability checks instead of optional references.
Keep shared wiring helpers aware of Functions destinations.

When it happens

Trigger: Calling WithReference(...) on an Azure Functions project resource with the optional parameter set to true (via the optional-reference overloads of the reference APIs).

Common situations: Reusing a shared helper that wires references optionally for all projects; copy-pasting reference code from a regular project resource to a Functions resource with optional flags enabled.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.Functions/AzureFunctionsProjectResourceExtensions.cs:371

            source.Resource.ApplyAzureFunctionsConfiguration(context.EnvironmentVariables, connectionName);
        });
    }

    internal static IResourceBuilder<AzureFunctionsProjectResource>? TryWithReference(
        IResourceBuilder<AzureFunctionsProjectResource> destination,
        IResourceBuilder<IResource> source,
        string? connectionName,
        bool optional,
        string? name)
    {
        if (source.Resource is not IResourceWithConnectionString || source.Resource is not IResourceWithAzureFunctionsConfig azureFunctionsConfig)
        {
            return null;
        }

        if (optional)
        {
            throw new InvalidOperationException("Optional references are not supported for Azure Functions resources.");
        }

        if (name is not null)
        {
            throw new InvalidOperationException("Named service references are not supported for Azure Functions resources.");
        }

        destination.WithReferenceRelationship(source.Resource);

        return destination.WithEnvironment(context =>
        {
            connectionName ??= source.Resource.Name;
            azureFunctionsConfig.ApplyAzureFunctionsConfiguration(context.EnvironmentVariables, connectionName);
        });
    }

    private static string CreateDefaultStorageName(this IDistributedApplicationBuilder builder)
    {

View on GitHub (pinned to 25830f84bd)