{"record":{"id":"1e58dce6ca900be2","repo":"vitest-dev/vitest","slug":"vitest-web-worker-cannot-initiate-a-custom-web","errorCode":null,"errorMessage":"[@vitest/web-worker] Cannot initiate a custom Web Worker. \"${name}\" is not supported in this environment. Please, consider using jsdom or happy-dom environment.","messagePattern":"\\[@vitest/web-worker\\] Cannot initiate a custom Web Worker\\. \"(.+?)\" is not supported in this environment\\. Please, consider using jsdom or happy-dom environment\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/web-worker/src/utils.ts","lineNumber":10,"sourceCode":"import type { Debugger } from 'obug'\nimport type { CloneOption } from './types'\nimport ponyfillStructuredClone from '@ungap/structured-clone'\nimport { createDebug } from 'obug'\n\nexport const debug: Debugger = createDebug('vitest:web-worker')\n\nexport function assertGlobalExists(name: string): void {\n  if (!(name in globalThis)) {\n    throw new Error(\n      `[@vitest/web-worker] Cannot initiate a custom Web Worker. \"${name}\" is not supported in this environment. Please, consider using jsdom or happy-dom environment.`,\n    )\n  }\n}\n\nfunction createClonedMessageEvent(\n  data: any,\n  transferOrOptions: StructuredSerializeOptions | Transferable[] | undefined,\n  clone: CloneOption,\n) {\n  const transfer = Array.isArray(transferOrOptions)\n    ? transferOrOptions\n    : transferOrOptions?.transfer\n\n  debug('clone worker message %o', data)\n  const origin = typeof location === 'undefined' ? undefined : location.origin\n  const ports = transfer?.filter((t): t is MessagePort => t instanceof MessagePort)\n","sourceCodeStart":1,"sourceCodeEnd":28,"githubUrl":"https://github.com/vitest-dev/vitest/blob/1fa9837ec26533512fdcad8baebf249771bd340a/packages/web-worker/src/utils.ts#L1-L28","documentation":"assertGlobalExists guards the custom Worker constructor: @vitest/web-worker needs browser globals (such as Worker, MessageChannel, structuredClone) to exist on globalThis. In a bare Node test environment those globals are absent, so the helper throws this error at construction time, before any worker code runs, and points to jsdom or happy-dom as the fix.","triggerScenarios":"Instantiating a Worker through the @vitest/web-worker constructor while the Vitest environment is node (no DOM shim). The check runs synchronously during Worker construction, via assertGlobalExists called with the missing global name.","commonSituations":"Default environment left as node; forgot to set jsdom or happy-dom; an environment shim package is missing or an incompatible version that does not define the required global; an SSR-style test that imports worker code incidentally.","solutions":["Switch the Vitest environment to a DOM provider: set environment: 'jsdom' (or 'happy-dom') in the config, or pass --environment happy-dom.","Install the environment package: npm i -D jsdom (or happy-dom).","Scope it per file with a comment directive at the top of the test: // @vitest-environment happy-dom."],"exampleFix":"// before\n// @vitest-environment node\nnew MyWorker(url)  // throws\n\n// after\n// @vitest-environment happy-dom\nnew MyWorker(url)","handlingStrategy":"validation","validationCode":"function environmentSupportsWorker() {\n  return typeof globalThis !== 'undefined'\n    && 'Worker' in globalThis\n}\nif (!environmentSupportsWorker()) {\n  throw new Error('Current Vitest environment lacks Worker; set environment to jsdom or happy-dom.')\n}","typeGuard":"function hasWorkerGlobal(g: typeof globalThis): g is typeof globalThis & { Worker: typeof Worker } {\n  return typeof g !== 'undefined' && 'Worker' in g\n}","tryCatchPattern":"try {\n  const worker = new CustomWorker(url)\n} catch (e) {\n  if (e instanceof Error && /not supported in this environment/.test(e.message)) {\n    console.warn('Skipping worker test: set // @vitest-environment happy-dom')\n    return\n  }\n  throw e\n}","preventionTips":["Pin the environment in vitest.config (environment: 'happy-dom') for any project using web workers.","Add a // @vitest-environment directive to files that instantiate workers.","Install the environment shim package (jsdom or happy-dom) as a dev dependency.","Guard worker-instantiating tests with an environmentSupportsWorker() check so they skip cleanly under node."],"tags":["web-worker","environment","dom","configuration"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}