{"record":{"id":"a774148ba505737d","repo":"microsoft/aspire","slug":"gatewayappsannotation-not-found-on-resource","errorCode":null,"errorMessage":"GatewayAppsAnnotation not found on resource.","messagePattern":"GatewayAppsAnnotation not found on resource\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Blazor/BlazorGatewayExtensions.cs","lineNumber":706,"sourceCode":"    {\n        if (resource.TryGetLastAnnotation<GatewayAppsAnnotation>(out var existing))\n        {\n            return existing;\n        }\n\n        var newAnnotation = new GatewayAppsAnnotation();\n        resource.Annotations.Add(newAnnotation);\n        return newAnnotation;\n    }\n\n    private static List<GatewayAppRegistration> GetRegisteredApps(IResource resource)\n    {\n        if (resource.TryGetLastAnnotation<GatewayAppsAnnotation>(out var apps))\n        {\n            return apps.Apps;\n        }\n\n        throw new InvalidOperationException(\"GatewayAppsAnnotation not found on resource.\");\n    }\n\n    private static List<EndpointAnnotation> GetAllocatedEndpoints(IResource resource)\n    {\n        var endpoints = new List<EndpointAnnotation>();\n        foreach (var annotation in resource.Annotations)\n        {\n            if (annotation is EndpointAnnotation ep && ep.AllocatedEndpoint is not null)\n            {\n                endpoints.Add(ep);\n            }\n        }\n        return endpoints;\n    }\n\n    private static ImmutableArray<UrlSnapshot> BuildClientUrls(\n        List<EndpointAnnotation> endpoints, string pathPrefix)\n    {","sourceCodeStart":688,"sourceCodeEnd":724,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Blazor/BlazorGatewayExtensions.cs#L688-L724","documentation":"GetRegisteredApps reads the GatewayAppsAnnotation from the gateway resource to enumerate the registered Blazor apps. If the annotation is absent — meaning WithBlazorApp (or equivalent registration) was never applied to this resource — the helper throws an InvalidOperationException.","triggerScenarios":"Environment-callback or endpoint wiring code calls GetRegisteredApps on a gateway resource that never received GatewayAppsAnnotation, e.g. invoking WithBlazorApp-dependent configuration on a gateway built without registering any Blazor app.","commonSituations":"Calling low-level extension methods out of order; applying WithEnvironment-based wiring manually before any WithBlazorApp call; a refactor renamed/removed the registration call.","solutions":["Call gateway.WithBlazorApp(...) (which adds GatewayAppsAnnotation) before code that reads registered apps.","Register at least one Blazor app with the gateway via the documented extension APIs.","Guard with resource.TryGetLastAnnotation<GatewayAppsAnnotation> before consuming apps.","Ensure you're inspecting the gateway resource itself, not the client app resource."],"exampleFix":"// before\nvar apps = GetRegisteredApps(gateway.Resource);\n// after\nif (!gateway.Resource.TryGetLastAnnotation<GatewayAppsAnnotation>(out var appsAnn))\n{\n    throw new InvalidOperationException(\"Call WithBlazorApp on the gateway before starting it.\");\n}\nvar apps = appsAnn.Apps;","handlingStrategy":"type-guard","validationCode":"if (!gateway.Resource.TryGetLastAnnotation<GatewayAppsAnnotation>(out var apps))\n{\n    throw new InvalidOperationException(\"No Blazor apps registered; call WithBlazorApp first.\");\n}","typeGuard":"bool TryGetGatewayApps(IResource r, out IReadOnlyList<BlazorApp> apps)\n{\n    if (r.TryGetLastAnnotation<GatewayAppsAnnotation>(out var a)) { apps = a.Apps; return true; }\n    apps = default; return false;\n}","tryCatchPattern":"try { var apps = GetRegisteredApps(gateway.Resource); } catch (InvalidOperationException ex) when (ex.Message.Contains(\"GatewayAppsAnnotation\")) { logger.LogError(ex, \"Call WithBlazorApp before consuming gateway apps\"); throw; }","preventionTips":["Always register apps via WithBlazorApp before gateway-dependent wiring.","Never hand-build gateway resources without the annotation.","Use TryGetLastAnnotation defensively in custom extension code."],"tags":["blazor","gateway","annotation","internal-invariant","wasm"],"backgroundTag":"internal-invariant-violation","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"}