The custom event ' ' cannot have the same name as its…

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 options.browserEventName is set and equals eventName. Blazor aliases a browser event by wrapping it; if the custom name matches the browser name the handler fires twice (once for the native event, once for the wrapper). The check explicitly prevents this double-trigger.

Solutions

Choose a distinct custom event name that differs from the browserEventName (e.g. 'customclick' wrapping 'click').
If you don't actually need aliasing, omit browserEventName entirely.
Document the chosen custom name so consumers reference it via @oneventname.

Example fix

// before (throws)
registerCustomEventType('click', { browserEventName: 'click', createEventArgs: e => ({ x: e.clientX }) });

// after
registerCustomEventType('customclick', { browserEventName: 'click', createEventArgs: e => ({ x: e.clientX }) });
// in Razor: @oncustomclick="..."

Defensive patterns

Strategy: validation

Validate before calling

function registerAlias(customName: string, browserName: string, options: EventTypeOptions) {
  if (customName === browserName) {
    throw new Error(`Custom name '${customName}' must differ from browserEventName '${browserName}'.`);
  }
  registerCustomEventType(customName, { ...options, browserEventName: browserName });
}

Type guard

function isValidAlias(customName: string, browserName?: string): boolean {
  return !browserName || customName !== browserName;
}

Prevention

Always pick a distinct custom event name when aliasing a browser event.
Omit browserEventName entirely if you are not aliasing.
Add a unit test asserting customName !== browserEventName.

When it happens

Trigger: Calling registerCustomEventType('click', { browserEventName: 'click', ... }) or any pair where the first arg equals options.browserEventName.

Common situations: Developer wants to 'extend' a native event and reuses its name by mistake; copy-pasting a registration and forgetting to rename the custom event.

Related errors

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

Appendix: 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 3600ca084e)