dotnet/aspnetcore · error · Error

The options parameter is required.

Error message

The options parameter is required.

What it means

Thrown by registerCustomEventType when the options argument is falsy. Custom event registration requires an EventTypeOptions object (at minimum to hold createEventArgs / browserEventName), so passing undefined/null/0 is rejected.

Source

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

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

export interface EventTypeOptions {
  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) {

View on GitHub (pinned to 294cab2f9b)

Solutions

1. Always pass an EventTypeOptions object, even if only { createEventArgs: e => ({}) }.
2. If you have nothing to customize, pass an empty object {} rather than undefined.
3. Add a TypeScript check that options is non-null before calling registerCustomEventType.

Example fix

// before
Blazor.registerCustomEventType('myevent'); // throws

// after
Blazor.registerCustomEventType('myevent', {
  createEventArgs: e => ({ detail: e.detail })
});

// Validate options before registering.
function register(name: string, options?: EventTypeOptions) {
  if (!options) throw new Error('options required');
  Blazor.registerCustomEventType(name, options);
}

function isValidOptions(o: unknown): o is EventTypeOptions {
  return !!o && typeof o === 'object';
}

When it happens

Trigger: Calling Blazor.registerCustomEventType('myevent') with no second argument, or passing an explicitly undefined options.

Common situations: Forgetting the options argument; conditionally building options and passing undefined when a branch is skipped; refactor that drops the options object.

Related errors

• The custom event '${eventName}' cannot have the same name as
• The event '${eventName}' is already registered.
• initialParameters must be an object, even if empty.
• descriptor must be defined when using a descriptor.
• sequence must be defined when using a descriptor.

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