{"record":{"id":"ab89aefd0631d8e2","repo":"cypress-io/cypress","slug":"esm-plugin-config-value-name-must-be-an-array","errorCode":null,"errorMessage":"ESM plugin config value '${name}' must be an array of strings","messagePattern":"ESM plugin config value '(.+?)' must be an array of strings","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"npm/vite-plugin-cypress-esm/src/index.ts","lineNumber":46,"sourceCode":"   * Module A imports Module B\n   * Adding `A` to `ignoreModuleList` will prevent usages of `B` within `A` from being stubbed\n   */\n  ignoreModuleList?: string[]\n  /**\n   * Array of picomatch patterns of imports to ignore (use unaltered module). Any ignored\n   * imports will not support stub/spy. Use this to remedy usages of a proxied module that cause\n   * problems.\n   *\n   * Example:\n   * Module A imports Module B\n   * Adding `B` to `ignoreImportList` will prevent usages of `B` within `A` from being stubbed\n   */\n  ignoreImportList?: string[]\n}\n\nconst assertIsArrayOrUndefined = (name: string, value: any): void => {\n  if (value && (!Array.isArray(value) || value.some((val) => typeof val !== 'string'))) {\n    throw new Error(`ESM plugin config value '${name}' must be an array of strings`)\n  }\n}\n\nexport const CypressEsm = (options?: CypressEsmOptions): Plugin => {\n  // Validate config\n  assertIsArrayOrUndefined('ignoreList', options?.ignoreList)\n  assertIsArrayOrUndefined('ignoreModuleList', options?.ignoreModuleList)\n  assertIsArrayOrUndefined('ignoreImportList', options?.ignoreImportList)\n\n  const ignoreModuleList = ([] as string[]).concat(options?.ignoreModuleList ?? []).concat(options?.ignoreList ?? [])\n  const ignoreImportList = options?.ignoreImportList ?? []\n  const ignoreModuleMatcher = picomatch(ignoreModuleList)\n  const ignoreImportMatcher = picomatch(ignoreImportList)\n\n  /**\n   * If a module ID is explicitly ignored then do not proxify it\n   *\n   * @param moduleId","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/cypress-io/cypress/blob/0d85fdc91230885bca0a91df278312800a48b727/npm/vite-plugin-cypress-esm/src/index.ts#L28-L64","documentation":"Thrown by assertIsArrayOrUndefined in @cypress/vite-plugin-cypress-esm when validating the plugin options ignoreList, ignoreModuleList, and ignoreImportList. Each must be either undefined or an array containing only strings. Any other shape (object, number, single string, or an array with non-string elements) is rejected because the plugin feeds these arrays into picomatch matchers that require string inputs.","triggerScenarios":"Instantiating `CypressEsm({ ignoreList: ... })` (or ignoreModuleList / ignoreImportList) with a non-array value or an array containing non-strings. assertIsArrayOrUndefined runs at plugin creation time, so the throw happens during Vite plugin setup, before the server starts.","commonSituations":"Passing a single string instead of an array (`ignoreModuleList: 'lodash'`), passing an object keyed by module name, or a config builder that conditionally includes a non-string element.","solutions":["Wrap single values in an array: `ignoreModuleList: ['lodash']` instead of `'lodash'`.","Ensure every element is a string; coerce or remove numbers/objects.","If you want to disable a list, omit the option or set it to undefined (not null or empty object).","Validate the config before passing: `Array.isArray(x) && x.every(v => typeof v === 'string')`."],"exampleFix":"// before\nCypressEsm({ ignoreModuleList: 'lodash', ignoreImportList: { react: true } })\n// after\nCypressEsm({ ignoreModuleList: ['lodash'], ignoreImportList: ['react'] })","handlingStrategy":"type-guard","validationCode":"function asStringArray(v: unknown): string[] | undefined {\n  if (v == null) return undefined\n  if (!Array.isArray(v) || v.some(x => typeof x !== 'string')) throw new Error('expected string[]')\n  return v\n}","typeGuard":"const isStringArrayOrUndef = (v: unknown): v is string[] | undefined => v == null || (Array.isArray(v) && v.every(x => typeof x === 'string'))","tryCatchPattern":null,"preventionTips":["Always wrap list options in arrays, even singletons.","Validate option shapes at the config-builder boundary before passing to CypressEsm.","Use a typed CypressEsmOptions interface so the compiler rejects non-arrays at authoring time."],"tags":["vite","plugin","esm","validation","config"],"backgroundTag":null,"analyzedSha":"0d85fdc91230885bca0a91df278312800a48b727","analyzedAt":"2026-08-12T16:24:28.056Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}