{"record":{"id":"10b8917aee2c8e43","repo":"dotnet/aspnetcore","slug":"the-options-parameter-is-required","errorCode":null,"errorMessage":"The options parameter is required.","messagePattern":"The options parameter is required\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/Components/Web.JS/src/Rendering/Events/EventTypes.ts","lineNumber":17,"sourceCode":"// Licensed to the .NET Foundation under one or more agreements.\n// The .NET Foundation licenses this file to you under the MIT license.\n\nexport interface EventTypeOptions {\n  browserEventName?: string;\n  createEventArgs?: (event: Event) => unknown;\n}\n\nconst eventTypeRegistry: Map<string, EventTypeOptions> = new Map();\nconst browserEventNamesToAliases: Map<string, string[]> = new Map();\nconst createBlankEventArgsOptions: EventTypeOptions = { createEventArgs: () => ({}) };\n\nexport const eventNameAliasRegisteredCallbacks: ((aliasEventName: string, browserEventName) => void)[] = [];\n\nexport function registerCustomEventType(eventName: string, options: EventTypeOptions): void {\n  if (!options) {\n    throw new Error('The options parameter is required.');\n  }\n\n  // There can't be more than one registration for the same event name because then we wouldn't\n  // know which eventargs data to supply.\n  if (eventTypeRegistry.has(eventName)) {\n    throw new Error(`The event '${eventName}' is already registered.`);\n  }\n\n  // When aliasing a browser event, the custom event name must be different from the browser event name\n  // to avoid double-triggering (once for the browser event, once for the custom event wrapper)\n  if (options.browserEventName && eventName === options.browserEventName) {\n    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.`);\n  }\n\n  // If applicable, register this as an alias of the given browserEventName\n  if (options.browserEventName) {\n    const aliasGroup = browserEventNamesToAliases.get(options.browserEventName);\n    if (aliasGroup) {","sourceCodeStart":1,"sourceCodeEnd":35,"githubUrl":"https://github.com/dotnet/aspnetcore/blob/3600ca084e9c8b5f4174fc5e747f4c52d2100806/src/Components/Web.JS/src/Rendering/Events/EventTypes.ts#L1-L35","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nBlazor.registerCustomEventType('myevent'); // no options -> throw\n\n// after\nBlazor.registerCustomEventType('myevent', { createEventArgs: e => ({ value: (e as any).detail }) });","handlingStrategy":"validation","validationCode":"function register(name: string, options: EventTypeOptions | undefined) {\n  if (!options) throw new Error('options required');\n  Blazor.registerCustomEventType(name, options);\n}","typeGuard":"function isEventTypeOptions(v: unknown): v is EventTypeOptions {\n  return !!v && (typeof (v as any).createEventArgs === 'function' || 'browserEventName' in (v as any));\n}","tryCatchPattern":"try { Blazor.registerCustomEventType('myevent', options); }\ncatch (e) { if (/options parameter is required/.test(e.message)) { /* build options, retry */ } throw e; }","preventionTips":["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."],"tags":["events","registration","interop","argument-validation","blazor"],"backgroundTag":null,"analyzedSha":"3600ca084e9c8b5f4174fc5e747f4c52d2100806","analyzedAt":"2026-08-11T16:32:30.678Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}