{"record":{"id":"1b80e995ad53fd1f","repo":"evanw/esbuild","slug":"onload-call-is-missing-a-filter","errorCode":null,"errorMessage":"onLoad() call is missing a filter","messagePattern":"onLoad\\(\\) call is missing a filter","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/shared/common.ts","lineNumber":1327,"sourceCode":"          let registeredNote = extractCallerV8(new Error(registeredText), streamIn, 'onResolve')\n          let keys: OptionKeys = {}\n          let filter = getFlag(options, keys, 'filter', mustBeRegExp)\n          let namespace = getFlag(options, keys, 'namespace', mustBeString)\n          checkForInvalidFlags(options, keys, `in onResolve() call for plugin ${quote(name)}`)\n          if (filter == null) throw new Error(`onResolve() call is missing a filter`)\n          let id = nextCallbackID++\n          onResolveCallbacks[id] = { name: name!, callback, note: registeredNote }\n          plugin.onResolve.push({ id, filter: jsRegExpToGoRegExp(filter), namespace: namespace || '' })\n        },\n\n        onLoad(options, callback) {\n          let registeredText = `This error came from the \"onLoad\" callback registered here:`\n          let registeredNote = extractCallerV8(new Error(registeredText), streamIn, 'onLoad')\n          let keys: OptionKeys = {}\n          let filter = getFlag(options, keys, 'filter', mustBeRegExp)\n          let namespace = getFlag(options, keys, 'namespace', mustBeString)\n          checkForInvalidFlags(options, keys, `in onLoad() call for plugin ${quote(name)}`)\n          if (filter == null) throw new Error(`onLoad() call is missing a filter`)\n          let id = nextCallbackID++\n          onLoadCallbacks[id] = { name: name!, callback, note: registeredNote }\n          plugin.onLoad.push({ id, filter: jsRegExpToGoRegExp(filter), namespace: namespace || '' })\n        },\n\n        onDispose(callback) {\n          onDisposeCallbacks.push(callback)\n        },\n\n        esbuild: streamIn.esbuild,\n      })\n\n      // Await a returned promise if there was one. This allows plugins to do\n      // some asynchronous setup while still retaining the ability to modify\n      // the build options. This deliberately serializes asynchronous plugin\n      // setup instead of running them concurrently so that build option\n      // modifications are easier to reason about.\n      if (promise) await promise","sourceCodeStart":1309,"sourceCodeEnd":1345,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/shared/common.ts#L1309-L1345","documentation":"When a plugin registers an `onLoad` callback (lib/shared/common.ts:1327), esbuild reads `options.filter` with `mustBeRegExp` and throws if it is null/undefined. As with onResolve, the filter limits which module paths the load callback handles and is required.","triggerScenarios":"Calling `build.onLoad({}, callback)` or `build.onLoad({ namespace: 'ns' }, callback)` without a `filter` RegExp.","commonSituations":"Forgetting the filter; passing a glob string instead of a RegExp; copying an onResolve registration and dropping the filter.","solutions":["Pass a `filter` RegExp, e.g. `build.onLoad({ filter: /\\.css$/, namespace: 'file' }, cb)`.","Use `/.*/` only when you genuinely need every module and understand the cost.","Ensure the value is a RegExp, not a string glob."],"exampleFix":"// before\nbuild.onLoad({ namespace: 'ns' }, args => { ... });\n// after\nbuild.onLoad({ filter: /.*/, namespace: 'ns' }, args => { ... });","handlingStrategy":"validation","validationCode":"function registerOnLoad(build, opts, cb) {\n  if (!(opts.filter instanceof RegExp)) throw new Error('onLoad requires a filter RegExp');\n  build.onLoad(opts, cb);\n}","typeGuard":"function hasOnLoadFilter(o: any): o is { filter: RegExp } {\n  return !!o && o.filter instanceof RegExp;\n}","tryCatchPattern":null,"preventionTips":["Always pass a RegExp literal as filter.","Scope onLoad by namespace + filter to avoid unnecessary work."],"tags":["plugins","onload","validation","api-misuse"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}