{"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":"Error","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/3600ca084e9c8b5f4174fc5e747f4c52d2100806/src/Components/Web.JS/src/Services/NavigationUtils.ts#L83-L119","documentation":"Programmatic enhanced navigation (NavigationManager.NavigateTo with forceLoad=false under enhanced nav) is dispatched to a single registered handler attached by the enhanced-navigation subsystem. If performProgrammaticEnhancedNavigation is called and no handler has been attached via attachProgrammaticEnhancedNavigationHandler, the framework cannot route the request and throws — hasProgrammaticEnhancedNavigationHandler exists to let callers check first.","triggerScenarios":"Thrown at line 101 when performProgrammaticEnhancedNavigation(...) is called but programmaticEnhancedNavigationHandler is still undefined. Occurs if enhanced navigation is not active (no enhanced nav listener attached) but code requests a programmatic enhanced navigation.","commonSituations":"Calling NavigateTo from a component before enhanced navigation is initialized; disabling enhanced navigation via Blazor.start config while still calling enhanced nav interop; rendering a component in a non-enhanced-nav context (e.g. static SSR) that assumes enhanced nav exists.","solutions":["Check hasProgrammaticEnhancedNavigationHandler() before requesting a programmatic enhanced navigation.","Ensure enhanced navigation is enabled and Blazor has started before issuing navigation calls.","Use NavigateTo with forceLoad=true as a fallback when enhanced nav is unavailable.","Verify Blazor.start completed and the enhanced-nav listener is attached."],"exampleFix":"// before\nNavigationManager.NavigateTo(url);\n// after: guard for enhanced nav availability\nif (hasProgrammaticEnhancedNavigationHandler()) {\n  performProgrammaticEnhancedNavigation(url, false);\n} else {\n  // full page load fallback\n  window.location.href = url;\n}","handlingStrategy":"validation","validationCode":"import { hasProgrammaticEnhancedNavigationHandler } from './NavigationUtils';\n// before calling performProgrammaticEnhancedNavigation\nif (!hasProgrammaticEnhancedNavigationHandler()) {\n  // fallback to full page load\n  window.location.href = absoluteInternalHref;\n  return;\n}","typeGuard":null,"tryCatchPattern":"try {\n  performProgrammaticEnhancedNavigation(href, replace);\n} catch (e) {\n  if (/No enhanced programmatic navigation handler/i.test((e as Error).message)) {\n    window.location.href = href;\n  } else throw e;\n}","preventionTips":["Always check hasProgrammaticEnhancedNavigationHandler before programmatic enhanced nav.","Provide a full-page-load fallback path.","Ensure Blazor.start completed and enhanced nav initialized.","Treat enhanced nav as best-effort, not guaranteed."],"tags":["blazor","navigation","enhanced-navigation","handler","initialization"],"backgroundTag":null,"analyzedSha":"3600ca084e9c8b5f4174fc5e747f4c52d2100806","analyzedAt":"2026-08-11T16:32:30.678Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}