What causes "The event '${eventName}' is already registered." in dotnet/aspnetcore?

Choose a unique, non-native event name (e.g. 'myapp:custom' rather than 'click').

dotnet/aspnetcore · error · Error

The event '${eventName}' is already registered.

Error message

The event '${eventName}' is already registered.

What it means

Thrown by registerCustomEventType when eventName already exists in the eventTypeRegistry. Each event name maps to exactly one createEventArgs function; a second registration would be ambiguous, so it is rejected. Built-in DOM events (click, input, etc.) are pre-registered at module load.

Source

Thrown at src/Components/Web.JS/src/Rendering/Events/EventTypes.ts:23

  browserEventName?: string;
  createEventArgs?: (event: Event) => unknown;
}

const eventTypeRegistry: Map<string, EventTypeOptions> = new Map();
const browserEventNamesToAliases: Map<string, string[]> = new Map();
const createBlankEventArgsOptions: EventTypeOptions = { createEventArgs: () => ({}) };

export const eventNameAliasRegisteredCallbacks: ((aliasEventName: string, browserEventName) => void)[] = [];

export function registerCustomEventType(eventName: string, options: EventTypeOptions): void {
  if (!options) {
    throw new Error('The options parameter is required.');
  }

  // There can't be more than one registration for the same event name because then we wouldn't
  // know which eventargs data to supply.
  if (eventTypeRegistry.has(eventName)) {
    throw new Error(`The event '${eventName}' is already registered.`);
  }

  // When aliasing a browser event, the custom event name must be different from the browser event name
  // to avoid double-triggering (once for the browser event, once for the custom event wrapper)
  if (options.browserEventName && eventName === options.browserEventName) {
    throw new Error(`The custom event '${eventName}' cannot have the same name as its browserEventName '${options.browserEventName}'. Choose a different name for the custom event.`);
  }

  // If applicable, register this as an alias of the given browserEventName
  if (options.browserEventName) {
    const aliasGroup = browserEventNamesToAliases.get(options.browserEventName);
    if (aliasGroup) {
      aliasGroup.push(eventName);
    } else {
      browserEventNamesToAliases.set(options.browserEventName, [eventName]);
    }

    // For developer convenience, it's allowed to register the custom event type *after*

View on GitHub (pinned to 294cab2f9b)

Solutions

Choose a unique, non-native event name (e.g. 'myapp:custom' rather than 'click').
Guard against double-registration in HMR by checking before registering, or moving registration to a single init module.
Avoid shadowing built-in event names listed in EventTypes.ts.

Example fix

// before
Blazor.registerCustomEventType('click', { ... }); // collides with built-in

// after
Blazor.registerCustomEventType('myapp:click', { ... });

Defensive patterns

Strategy: validation

Validate before calling

// Check before registering to avoid duplicate/HMR double-register.
if (!isRegistered('myevent')) {
  Blazor.registerCustomEventType('myevent', { createEventArgs: e => ({}) });
}

Try / catch

try { Blazor.registerCustomEventType(name, opts); }
catch (e) {
  if (/already registered/i.test(e.message)) return; // idempotent on HMR
  throw e;
}

Prevention

Use unique custom event names that don't collide with native DOM events.
Centralize registration in one module to avoid double-loads under HMR.
Guard with an 'already registered' check before re-registering.

When it happens

Trigger: Calling registerCustomEventType with a name you already registered, or with a name that collides with a built-in event (e.g. 'click', 'change', 'input').

Common situations: Registering the same custom event in a module that loads twice (HMR); naming a custom event after a native DOM event; library + app both registering the same event name.

Related errors

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