{"record":{"id":"1cbcd1a2216b1bd0","repo":"microsoft/aspire","slug":"optional-references-are-not-supported-for-azure-functions","errorCode":null,"errorMessage":"Optional references are not supported for Azure Functions resources.","messagePattern":"Optional references are not supported for Azure Functions resources\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Azure.Functions/AzureFunctionsProjectResourceExtensions.cs","lineNumber":371,"sourceCode":"            source.Resource.ApplyAzureFunctionsConfiguration(context.EnvironmentVariables, connectionName);\n        });\n    }\n\n    internal static IResourceBuilder<AzureFunctionsProjectResource>? TryWithReference(\n        IResourceBuilder<AzureFunctionsProjectResource> destination,\n        IResourceBuilder<IResource> source,\n        string? connectionName,\n        bool optional,\n        string? name)\n    {\n        if (source.Resource is not IResourceWithConnectionString || source.Resource is not IResourceWithAzureFunctionsConfig azureFunctionsConfig)\n        {\n            return null;\n        }\n\n        if (optional)\n        {\n            throw new InvalidOperationException(\"Optional references are not supported for Azure Functions resources.\");\n        }\n\n        if (name is not null)\n        {\n            throw new InvalidOperationException(\"Named service references are not supported for Azure Functions resources.\");\n        }\n\n        destination.WithReferenceRelationship(source.Resource);\n\n        return destination.WithEnvironment(context =>\n        {\n            connectionName ??= source.Resource.Name;\n            azureFunctionsConfig.ApplyAzureFunctionsConfiguration(context.EnvironmentVariables, connectionName);\n        });\n    }\n\n    private static string CreateDefaultStorageName(this IDistributedApplicationBuilder builder)\n    {","sourceCodeStart":353,"sourceCodeEnd":389,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Azure.Functions/AzureFunctionsProjectResourceExtensions.cs#L353-L389","documentation":"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.","triggerScenarios":"Calling WithReference(...) on an Azure Functions project resource with the optional parameter set to true (via the optional-reference overloads of the reference APIs).","commonSituations":"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.","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."],"exampleFix":"// before\nfunctionsProject.WithReference(redis, optional: true);\n\n// after\nfunctionsProject.WithReference(redis);","handlingStrategy":"validation","validationCode":"bool supportsOptional = destination is not AzureFunctionsProjectResource;","typeGuard":"static bool SupportsOptionalReference(IResourceBuilder<IResource> b) => b.Resource is not AzureFunctionsProjectResource;","tryCatchPattern":"try { functionsProject.WithReference(dep, optional: true); } catch (InvalidOperationException ex) when (ex.Message.Contains(\"Optional references\")) { /* fall back to required reference */ }","preventionTips":["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."],"tags":["aspire","azure-functions","withreference","unsupported"],"backgroundTag":"unsupported-operation","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}