dotnet/aspnetcore · error · Error

The custom event '${eventName}' cannot have the same name as

Error message

The custom event '${eventName}' cannot have the same name as its browserEventName '${options.browserEventName}'. Choose a different name for the custom event.

What it means

Thrown by registerCustomEventType when a browserEventName alias is supplied and the custom eventName equals it. Aliasing wraps a native event; if both names match the handler would fire twice (once natively, once via the alias), so Blazor requires them to differ.

Source

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

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*
    // some listeners for it are already present. Once the event name alias gets registered,
    // we have to notify any existing event delegators so they can update their delegated
    // events list.
    eventNameAliasRegisteredCallbacks.forEach(callback => callback(eventName, options.browserEventName));
  }

View on GitHub (pinned to 294cab2f9b)

Solutions

Give the custom event a distinct name from its browserEventName (e.g. custom 'custompaste' aliasing 'paste').
If you don't need aliasing, omit browserEventName entirely.

Example fix

// before
Blazor.registerCustomEventType('paste', { browserEventName: 'paste', createEventArgs: e => ({}) });

// after
Blazor.registerCustomEventType('custompaste', { browserEventName: 'paste', createEventArgs: e => ({}) });

Defensive patterns

Strategy: validation

Validate before calling

// Ensure custom name differs from aliased browser event.
function registerAlias(custom: string, browser: string, opts: EventTypeOptions) {
  if (custom === browser) throw new Error('custom name must differ from browserEventName');
  Blazor.registerCustomEventType(custom, { ...opts, browserEventName: browser });
}

Prevention

Namespace custom event names (e.g. 'myapp:paste') to avoid clashing with the aliased native event.
Omit browserEventName if you don't actually need aliasing.

When it happens

Trigger: Calling registerCustomEventType('paste', { browserEventName: 'paste', ... }) — same string for both the custom name and the aliased browser event.

Common situations: Author misunderstanding the alias feature (thinking you must name the custom event after the native one); copy-paste from docs where the names were meant to differ.

Related errors

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