{"record":{"id":"a31bb478a51c58a6","repo":"evanw/esbuild","slug":"quote-key-must-be-mustbe","errorCode":null,"errorMessage":"${quote(key)} must be ${mustBe}","messagePattern":"(.+?) must be (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/shared/common.ts","lineNumber":82,"sourceCode":"  typeof value === 'string' || typeof value === 'object' && value !== null && !Array.isArray(value) ? null : 'a string or an object'\n\nlet mustBeStringOrArrayOfStrings = (value: string | string[] | undefined): string | null =>\n  typeof value === 'string' || (Array.isArray(value) && value.every(x => typeof x === 'string')) ? null : 'a string or an array of strings'\n\nlet mustBeStringOrUint8Array = (value: string | Uint8Array | undefined): string | null =>\n  typeof value === 'string' || value instanceof Uint8Array ? null : 'a string or a Uint8Array'\n\nlet mustBeStringOrURL = (value: string | URL | undefined): string | null =>\n  typeof value === 'string' || value instanceof URL ? null : 'a string or a URL'\n\ntype OptionKeys = { [key: string]: boolean }\n\nfunction getFlag<T, K extends (keyof T & string)>(object: T, keys: OptionKeys, key: K, mustBeFn: (value: T[K]) => string | null): T[K] | undefined {\n  let value = object[key]\n  keys[key + ''] = true\n  if (value === undefined) return undefined\n  let mustBe = mustBeFn(value)\n  if (mustBe !== null) throw new Error(`${quote(key)} must be ${mustBe}`)\n  return value\n}\n\nfunction checkForInvalidFlags(object: Object, keys: OptionKeys, where: string): void {\n  for (let key in object) {\n    if (!(key in keys)) {\n      throw new Error(`Invalid option ${where}: ${quote(key)}`)\n    }\n  }\n}\n\nexport function validateInitializeOptions(options: types.InitializeOptions): types.InitializeOptions {\n  let keys: OptionKeys = Object.create(null)\n  let wasmURL = getFlag(options, keys, 'wasmURL', mustBeStringOrURL)\n  let wasmModule = getFlag(options, keys, 'wasmModule', mustBeWebAssemblyModule)\n  let worker = getFlag(options, keys, 'worker', mustBeBoolean)\n  checkForInvalidFlags(options, keys, 'in initialize() call')\n  return {","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/shared/common.ts#L64-L100","documentation":"Every esbuild option is type-checked by getFlag() at lib/shared/common.ts:77 against a `mustBe` predicate (mustBeBoolean, mustBeString, mustBeInteger, etc.). When an option key is present but its value fails the predicate, esbuild throws naming the key and the expected type. This catches silent misbehavior from loosely-typed config before it reaches the binary.","triggerScenarios":"Passing e.g. `bundle: 'true'` (string not boolean), `target: 2020` (number not string/array), `logLimit: '10'` (string not integer), `mangleProps: '/^_/'` (string not RegExp), or `sourcemap: 'yes'` where a boolean is required to build()/context()/transform().","commonSituations":"Loading options from JSON/env files where all values are strings; YAML parsing producing strings for unquoted tokens; passing numeric IDs where strings are expected; coercion gaps when forwarding user input.","solutions":["Coerce the value to the exact type the option expects (string->Boolean for flags, string->Number for integers, etc.) before calling esbuild.","Check the option's expected type in the esbuild docs and fix the source producing the wrong type.","Adopt esbuild's TypeScript types (BuildOptions/TransformOptions) so the editor flags the mismatch at authoring time."],"exampleFix":"// before (bundle as string from env)\nawait build({ entryPoints: ['app.ts'], bundle: process.env.BUNDLE })\n\n// after\nawait build({ entryPoints: ['app.ts'], bundle: process.env.BUNDLE === 'true' })","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"// Narrow each option to its expected type before calling esbuild.\nfunction asBoolean(v, fallback) {\n  if (v === undefined) return fallback\n  if (typeof v === 'boolean') return v\n  if (v === 'true') return true\n  if (v === 'false') return false\n  throw new TypeError(`expected boolean, got ${typeof v}: ${v}`)\n}\n// e.g. bundle: asBoolean(opts.bundle, false)","tryCatchPattern":null,"preventionTips":["Use esbuild's exported BuildOptions/TransformOptions TypeScript types for your config object.","When reading options from env/JSON, coerce to the documented type before forwarding.","Write a small zod/joi schema for config loaded from untrusted sources."],"tags":["config","validation","type-mismatch","options"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}