dotnet/aspnetcore · error

No enhanced programmatic navigation handler has been attache

Error message

No enhanced programmatic navigation handler has been attached

What it means

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.

Source

Thrown at src/Components/Web.JS/src/Services/NavigationUtils.ts:101

export function attachEnhancedNavigationListener(listener: typeof enhancedNavigationListener) {
  enhancedNavigationListener = listener;
}

export function notifyEnhancedNavigationListeners(internalDestinationHref: string, interceptedLink: boolean) {
  enhancedNavigationListener?.(internalDestinationHref, interceptedLink);
}

export function hasProgrammaticEnhancedNavigationHandler(): boolean {
  return programmaticEnhancedNavigationHandler !== undefined;
}

export function attachProgrammaticEnhancedNavigationHandler(handler: typeof programmaticEnhancedNavigationHandler) {
  programmaticEnhancedNavigationHandler = handler;
}

export function performProgrammaticEnhancedNavigation(absoluteInternalHref: string, replace: boolean): void {
  if (!programmaticEnhancedNavigationHandler) {
    throw new Error('No enhanced programmatic navigation handler has been attached');
  }

  programmaticEnhancedNavigationHandler(absoluteInternalHref, replace);
}

function toBaseUriWithoutTrailingSlash(baseUri: string) {
  return baseUri.substring(0, baseUri.lastIndexOf('/'));
}

let testAnchor: HTMLAnchorElement;
export function toAbsoluteUri(relativeUri: string): string {
  testAnchor = testAnchor || document.createElement('a');
  testAnchor.href = relativeUri;
  return testAnchor.href;
}

function eventHasSpecialKey(event: MouseEvent) {
  return event.ctrlKey || event.shiftKey || event.altKey || event.metaKey;

View on GitHub (pinned to 294cab2f9b)

Solutions

1. If you need enhanced programmatic navigation, ensure you load blazor.web.js (not blazor.server.js/blazor.webassembly.js) and that it initialized.
2. For Blazor Server/WebAssembly apps, use NavigationManager.NavigateTo with forceLoad:false for client-side routing instead of expecting enhanced nav.
3. Guard calls: check window.Blazor._internal or the enhanced-nav capability before invoking.
4. Wait for Blazor.start() to resolve before triggering navigation.

Example fix

<!-- before: blazor.server.js, expecting enhanced nav -->
<script src="_framework/blazor.server.js"></script>

<!-- after: blazor.web.js provides enhanced programmatic navigation -->
<script src="_framework/blazor.web.js"></script>

function hasEnhancedNavHandler(): boolean {
  return hasProgrammaticEnhancedNavigationHandler();
}

import { hasProgrammaticEnhancedNavigationHandler } from './NavigationUtils';

function canUseEnhancedNav(): boolean {
  return hasProgrammaticEnhancedNavigationHandler();
}

try {
  performProgrammaticEnhancedNavigation(href, false);
} catch (e) {
  if (/No enhanced programmatic navigation handler/.test((e as Error).message)) {
    location.href = href; // fall back to full page load
  } else { throw e; }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Enhanced navigation does not support making a non-GET reques
• Enhanced navigation does not support making a non-GET reques
• Cannot perform enhanced form submission that changes the URL
• ' {GetType().Name}' already initialized.
• ' {GetType().Name}' has not been initialized.

AI-assisted analysis of dotnet/aspnetcore@294cab2f9b (2026-08-06). Data as JSON: /api/errors/708504798695e13e. Report an issue: GitHub.