{"record":{"id":"d62e2314485a315f","repo":"evanw/esbuild","slug":"expected-onstart-callback-in-plugin-quote-name","errorCode":null,"errorMessage":"Expected onStart() callback in plugin ${quote(name)} to return an object","messagePattern":"Expected onStart\\(\\) callback in plugin (.+?) to return an object","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/shared/common.ts","lineNumber":1367,"sourceCode":"      return { ok: false, error: e, pluginName: name }\n    }\n  }\n\n  requestCallbacks['on-start'] = async (id, request: protocol.OnStartRequest) => {\n    // Reset the \"pluginData\" map before each new build to avoid a memory leak.\n    // This is done before each new build begins instead of after each build ends\n    // because I believe the current API doesn't restrict when you can call\n    // \"resolve\" and there may be some uses of it that call it around when the\n    // build ends, and we don't want to accidentally break those use cases.\n    details.clear()\n\n    let response: protocol.OnStartResponse = { errors: [], warnings: [] }\n    await Promise.all(onStartCallbacks.map(async ({ name, callback, note }) => {\n      try {\n        let result = await callback()\n\n        if (result != null) {\n          if (typeof result !== 'object') throw new Error(`Expected onStart() callback in plugin ${quote(name)} to return an object`)\n          let keys: OptionKeys = {}\n          let errors = getFlag(result, keys, 'errors', mustBeArray)\n          let warnings = getFlag(result, keys, 'warnings', mustBeArray)\n          checkForInvalidFlags(result, keys, `from onStart() callback in plugin ${quote(name)}`)\n\n          if (errors != null) response.errors!.push(...sanitizeMessages(errors, 'errors', details, name, undefined))\n          if (warnings != null) response.warnings!.push(...sanitizeMessages(warnings, 'warnings', details, name, undefined))\n        }\n      } catch (e) {\n        response.errors!.push(extractErrorMessageV8(e, streamIn, details, note && note(), name))\n      }\n    }))\n    sendResponse(id, response as any)\n  }\n\n  requestCallbacks['on-resolve'] = async (id, request: protocol.OnResolveRequest) => {\n    let response: protocol.OnResolveResponse = {}, name = '', callback, note\n    for (let id of request.ids) {","sourceCodeStart":1349,"sourceCodeEnd":1385,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/shared/common.ts#L1349-L1385","documentation":"When an `onStart` callback runs (lib/shared/common.ts:1367), its awaited return value must be `null`/`undefined` (meaning no messages) or a plain object optionally containing `errors` and `warnings` arrays. If it returns a truthy non-object (e.g. a string, number, array, boolean), esbuild throws this error. The thrown error is caught and surfaced as a build error attributed to the named plugin.","triggerScenarios":"An `onStart` callback that returns a string, number, boolean, or an array (instead of an object or null).","commonSituations":"Returning a status message string by mistake; returning a Promise that resolves to a non-object; forgetting to return `null` after doing work that has no messages.","solutions":["Return either `null`/`undefined` or an object `{ errors: [...], warnings: [...] }` from the onStart callback.","If you only do side effects, simply return nothing (undefined)."],"exampleFix":"// before\nbuild.onStart(async () => { return 'starting'; });\n// after\nbuild.onStart(async () => { /* side effects */ return null; });","handlingStrategy":"type-guard","validationCode":"function wrapOnStart(cb) {\n  return async () => { const r = await cb(); return r == null || (typeof r === 'object' && !Array.isArray(r)) ? r : null; };\n}","typeGuard":"function isOnStartResult(v: any): v is { errors?: any[]; warnings?: any[] } | null {\n  return v == null || (typeof v === 'object' && !Array.isArray(v));\n}","tryCatchPattern":null,"preventionTips":["Return null explicitly from onStart when you have nothing to report.","Avoid returning strings/numbers from these hooks."],"tags":["plugins","onstart","validation","callback-contract"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}