{"record":{"id":"ec32a3258ba8ede2","repo":"discordjs/discord.js","slug":"expected-workerbootstrap-to-not-be-used-within-the","errorCode":null,"errorMessage":"Expected WorkerBootstrap to not be used within the main thread","messagePattern":"Expected WorkerBootstrap to not be used within the main thread","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/ws/src/utils/WorkerBootstrapper.ts","lineNumber":47,"sourceCode":"}\n\n/**\n * Utility class for bootstrapping a worker thread to be used for sharding\n */\nexport class WorkerBootstrapper {\n\t/**\n\t * The data passed to the worker thread\n\t */\n\tprotected readonly data = workerData as WorkerData;\n\n\t/**\n\t * The shards that are managed by this worker\n\t */\n\tprotected readonly shards = new Collection<number, WebSocketShard>();\n\n\tpublic constructor() {\n\t\tif (isMainThread) {\n\t\t\tthrow new Error('Expected WorkerBootstrap to not be used within the main thread');\n\t\t}\n\t}\n\n\t/**\n\t * Helper method to initiate a shard's connection process\n\t */\n\tprotected async connect(shardId: number): Promise<void> {\n\t\tconst shard = this.shards.get(shardId);\n\t\tif (!shard) {\n\t\t\tthrow new RangeError(`Shard ${shardId} does not exist`);\n\t\t}\n\n\t\tawait shard.connect();\n\t}\n\n\t/**\n\t * Helper method to destroy a shard\n\t */","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/discordjs/discord.js/blob/a81ed8a306d37fdc746e26a634b6a42164ba2c8c/packages/ws/src/utils/WorkerBootstrapper.ts#L29-L65","documentation":"WorkerBootstrapper is the utility that boots shard management code inside a worker_threads worker; its constructor mirrors the strategy guard and throws if isMainThread is true. A main-thread worker bootstrapper makes no sense since it relies on parentPort to receive shard spawn instructions from the main thread. Use WebSocketManager directly on the main thread instead.","triggerScenarios":"Calling new WorkerBootstrapper() (or a subclass constructor) from the main entry file instead of from the file/module executed as a worker script, e.g. setting WorkerShardingStrategy's workerPath option to the same file that instantiates the bootstrapper on the main thread.","commonSituations":"Structuring a single entry file that both runs the bot and bootstraps workers without checking isMainThread; forgetting the main-thread guard pattern; copying the bootstrapper instantiation to the top of the workerPath script which the main thread also imports/executes.","solutions":["Only instantiate WorkerBootstrapper inside the script referenced as the worker path (executed by worker_threads), wrapped in an if (!isMainThread) branch.","On the main thread, construct WebSocketManager with WorkerShardingStrategy and pass options; let it spawn the workers that run the bootstrapper.","If the entry file is both main and worker, guard with isMainThread and run WorkerBootstrapper only in the worker branch."],"exampleFix":"// before (entry.js, runs as both main and worker)\nnew WorkerBootstrapper().start();\n// after\nimport { isMainThread } from 'node:worker_threads';\nif (isMainThread) {\n  const manager = new WebSocketManager({ ... });\n  await manager.spawn();\n} else {\n  new WorkerBootstrapper().start();\n}","handlingStrategy":"validation","validationCode":"import { isMainThread } from 'node:worker_threads';\nif (isMainThread) {\n  // main thread: run the manager, never the bootstrapper\n} else {\n  new WorkerBootstrapper().start();\n}","typeGuard":"const canUseWorkerBootstrapper = () => !isMainThread;","tryCatchPattern":"let bootstrapper;\ntry {\n  bootstrapper = new WorkerBootstrapper();\n} catch (err) {\n  if (err instanceof Error && /main thread/.test(err.message)) {\n    throw new Error('WorkerBootstrapper must live in the workerPath script, not the main entry');\n  } else throw err;\n}","preventionTips":["Put WorkerBootstrapper instantiation only in the file referenced by the worker sharding strategy's workerPath.","Follow the isMainThread branch pattern at the top of shared entry files.","Use @discordjs/ws's own examples/templates for worker sharding layout."],"tags":["worker-threads","nodejs","threading","misconfiguration"],"backgroundTag":"wrong-thread-context","analyzedSha":"a81ed8a306d37fdc746e26a634b6a42164ba2c8c","analyzedAt":"2026-08-30T04:07:22.193Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}