What causes "The options parameter is required." in dotnet/aspnetcore?

Pass an `EventTypeOptions` object with at least `createEventArgs` (and optionally `browserEventName`).

The options parameter is required.

Error message

The options parameter is required.

What it means

`registerCustomEventType` lets apps register a custom DOM event name with optional event-args mapping. The `options` object is required because it carries the `createEventArgs`/`browserEventName` configuration the registry stores. Passing nothing (or undefined) is a misuse — there is no valid registration to record — so it throws immediately before touching the registry maps.

Solutions

Pass an `EventTypeOptions` object with at least `createEventArgs` (and optionally `browserEventName`).
If you only need the event with blank args, pass `{ createEventArgs: () => ({}) }`.
Construct the options object unconditionally before registering, and double-check the argument is not undefined.
Register custom event types once at startup, before any component uses the event name.

Example fix

// before
Blazor.registerCustomEventType('myevent'); // no options -> throw

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

Defensive patterns

Strategy: validation

Validate before calling

function register(name: string, options: EventTypeOptions | undefined) {
  if (!options) throw new Error('options required');
  Blazor.registerCustomEventType(name, options);
}

Type guard

function isEventTypeOptions(v: unknown): v is EventTypeOptions {
  return !!v && (typeof (v as any).createEventArgs === 'function' || 'browserEventName' in (v as any));
}

Try / catch

try { Blazor.registerCustomEventType('myevent', options); }
catch (e) { if (/options parameter is required/.test(e.message)) { /* build options, retry */ } throw e; }

Prevention

Always pass an EventTypeOptions object with createEventArgs.
Use { createEventArgs: () => ({}) } when blank args suffice.
Build options unconditionally before registering.
Register custom event types once at startup.

When it happens

Trigger: Calling `Blazor.registerCustomEventType(eventName, options)` (or the underlying function) with `options` undefined/null — e.g. forgetting the second argument or passing a variable that evaluated to undefined.

Common situations: A custom-events registration with a missing options object; a typo'd second argument; conditional registration where the options weren't built before the call; an upgrade where the options shape changed and old code passes nothing.

Related errors

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

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