{"record":{"id":"708504798695e13e","repo":"dotnet/aspnetcore","slug":"no-enhanced-programmatic-navigation-handler-has-be","errorCode":null,"errorMessage":"No enhanced programmatic navigation handler has been attached","messagePattern":"No enhanced programmatic navigation handler has been attached","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/Components/Web.JS/src/Services/NavigationUtils.ts","lineNumber":101,"sourceCode":"export function attachEnhancedNavigationListener(listener: typeof enhancedNavigationListener) {\n  enhancedNavigationListener = listener;\n}\n\nexport function notifyEnhancedNavigationListeners(internalDestinationHref: string, interceptedLink: boolean) {\n  enhancedNavigationListener?.(internalDestinationHref, interceptedLink);\n}\n\nexport function hasProgrammaticEnhancedNavigationHandler(): boolean {\n  return programmaticEnhancedNavigationHandler !== undefined;\n}\n\nexport function attachProgrammaticEnhancedNavigationHandler(handler: typeof programmaticEnhancedNavigationHandler) {\n  programmaticEnhancedNavigationHandler = handler;\n}\n\nexport function performProgrammaticEnhancedNavigation(absoluteInternalHref: string, replace: boolean): void {\n  if (!programmaticEnhancedNavigationHandler) {\n    throw new Error('No enhanced programmatic navigation handler has been attached');\n  }\n\n  programmaticEnhancedNavigationHandler(absoluteInternalHref, replace);\n}\n\nfunction toBaseUriWithoutTrailingSlash(baseUri: string) {\n  return baseUri.substring(0, baseUri.lastIndexOf('/'));\n}\n\nlet testAnchor: HTMLAnchorElement;\nexport function toAbsoluteUri(relativeUri: string): string {\n  testAnchor = testAnchor || document.createElement('a');\n  testAnchor.href = relativeUri;\n  return testAnchor.href;\n}\n\nfunction eventHasSpecialKey(event: MouseEvent) {\n  return event.ctrlKey || event.shiftKey || event.altKey || event.metaKey;","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/dotnet/aspnetcore/blob/294cab2f9b2e03af6b953820c7ab497c3c8b7ad9/src/Components/Web.JS/src/Services/NavigationUtils.ts#L83-L119","documentation":"Thrown by performProgrammaticEnhancedNavigation (NavigationUtils.ts:101) when code requests an enhanced programmatic navigation but no handler has been attached via attachProgrammaticEnhancedNavigationHandler. The handler is registered by attachProgressivelyEnhancedNavigationListener (NavigationEnhancement.ts) which runs only when blazor.web.js is loaded and the enhanced-nav listener is set up. With blazor.server.js / blazor.webassembly.js the handler is never attached.","triggerScenarios":"Calling NavigationManager.NavigateTo (or refresh with enhanced nav expected) while no enhanced navigation listener is attached — e.g. on blazor.server.js/blazor.webassembly.js, or before blazor.web.js's enhanced listener initialized, or after it was detached.","commonSituations":"Using Blazor.navigateTo / refresh in a Blazor Server or WebAssembly (non-web) app expecting enhanced nav; calling navigation before Blazor.start completes; a Blazor Web App whose enhanced-nav listener was not attached due to an init error; mixing blazor.*.js bundles.","solutions":["If you need enhanced programmatic navigation, ensure you load blazor.web.js (not blazor.server.js/blazor.webassembly.js) and that it initialized.","For Blazor Server/WebAssembly apps, use NavigationManager.NavigateTo with forceLoad:false for client-side routing instead of expecting enhanced nav.","Guard calls: check window.Blazor._internal or the enhanced-nav capability before invoking.","Wait for Blazor.start() to resolve before triggering navigation."],"exampleFix":"<!-- before: blazor.server.js, expecting enhanced nav -->\n<script src=\"_framework/blazor.server.js\"></script>\n\n<!-- after: blazor.web.js provides enhanced programmatic navigation -->\n<script src=\"_framework/blazor.web.js\"></script>","handlingStrategy":"type-guard","validationCode":"function hasEnhancedNavHandler(): boolean {\n  return hasProgrammaticEnhancedNavigationHandler();\n}","typeGuard":"import { hasProgrammaticEnhancedNavigationHandler } from './NavigationUtils';\n\nfunction canUseEnhancedNav(): boolean {\n  return hasProgrammaticEnhancedNavigationHandler();\n}","tryCatchPattern":"try {\n  performProgrammaticEnhancedNavigation(href, false);\n} catch (e) {\n  if (/No enhanced programmatic navigation handler/.test((e as Error).message)) {\n    location.href = href; // fall back to full page load\n  } else { throw e; }\n}","preventionTips":["Load blazor.web.js when you need enhanced programmatic navigation.","Await Blazor.start() before navigating.","Use NavigationManager.NavigateTo with forceLoad for non-web bundles."],"tags":["blazor","enhanced-nav","navigation","bundle","initialization"],"analyzedSha":"294cab2f9b2e03af6b953820c7ab497c3c8b7ad9","analyzedAt":"2026-08-06T20:08:02.189Z","schemaVersion":2},"datasetVersion":"2026-08-06T23:17:07.152Z"}