microsoft/aspire · error · FileNotFoundException

not found at ' '. Ensure the Aspire.Hosting.Blazor package…

Error message

{scriptName} not found at '{scriptPath}'. Ensure the Aspire.Hosting.Blazor package includes the file as content.

What it means

GetScriptPath resolves bundled gateway scripts (e.g. Gateway.cs) from the Aspire.Hosting.Blazor assembly directory. If the expected script file is missing from disk next to the assembly, it throws FileNotFoundException telling you the package should include it as content.

Solutions

Reinstall/repair the Aspire.Hosting.Blazor NuGet package so Scripts/*.cs content files ship with it.
Verify Scripts/Gateway.cs exists next to Aspire.Hosting.Blazor.dll and fix the deployment to copy content files.
If building the package locally, fix the csproj content-include globs for the Scripts folder.
Run from a normal dotnet build/package layout instead of hand-copied assemblies.

Example fix

<!-- before: Scripts folder not included -->
<!-- after -->
<ItemGroup>
  <Content Include="Scripts\**\*" CopyToOutputDirectory="PreserveNewest" Pack="true" PackagePath="contentFiles" />
</ItemGroup>

Defensive patterns

Strategy: fallback

Validate before calling

var scriptPath = Path.Combine(Path.GetDirectoryName(typeof(BlazorGatewayExtensions).Assembly.Location)!, "Scripts", "Gateway.cs");
if (!File.Exists(scriptPath)) throw new InvalidOperationException($"Aspire.Hosting.Blazor content missing: {scriptPath}");

Try / catch

try { AddDotnetProjectBlazorGateway(builder, ...); } catch (FileNotFoundException ex) when (ex.Message.Contains("Ensure the Aspire.Hosting.Blazor package")) { logger.LogError(ex, "Reinstall Aspire.Hosting.Blazor; Scripts content not shipped"); throw; }

Prevention

Deploy the full package output, not hand-copied DLLs.
Verify package content files in CI when building Aspire locally.
Avoid publishes that trim content items from Aspire.Hosting.Blazor.

When it happens

Trigger: Calling AddDotnetProjectBlazorGateway/GetScriptPath when the assembly's directory lacks Scripts/<scriptName> — typically after copying only the DLL, using a broken/local build, or a packaging bug where content items weren't shipped.

Common situations: Non-standard deployment of the host assembly (xcopy of a single DLL); trimmed publish dropping content files; building the package locally without content globs; custom bin layout.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Blazor/BlazorGatewayExtensions.cs:586

                        /app/output/{{pathPrefix}}.endpoints.json
                """;
        });

        gateway.WithAnnotation(new ContainerFilesDestinationAnnotation
        {
            Source = companion.Resource,
            DestinationPath = "."
        });
    }

    private static string GetScriptPath(string scriptName)
    {
        var assemblyDir = Path.GetDirectoryName(typeof(BlazorGatewayExtensions).Assembly.Location)!;
        var scriptPath = Path.Combine(assemblyDir, "Scripts", scriptName);

        if (!File.Exists(scriptPath))
        {
            throw new FileNotFoundException(
                $"{scriptName} not found at '{scriptPath}'. Ensure the Aspire.Hosting.Blazor package includes the file as content.");
        }

        return scriptPath;
    }

    private const string AspireStorePathKey = "Aspire:Store:Path";

    /// <summary>
    /// Gets the Blazor-specific store path under the Aspire store directory.
    /// </summary>
    private static string GetBlazorStorePath(IDistributedApplicationBuilder builder)
    {
        var storePath = builder.Configuration[AspireStorePathKey]
            ?? builder.AppHostDirectory;

        return Path.Combine(storePath, ".aspire", "blazor");
    }

View on GitHub (pinned to 25830f84bd)