{"record":{"id":"a47398c7dfb4fe7c","repo":"tursodatabase/turso","slug":"method-name-must-be-invoked-only-from-the-main","errorCode":null,"errorMessage":"method ${name} must be invoked only from the main thread","messagePattern":"method (.+?) must be invoked only from the main thread","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"bindings/javascript/packages/wasm-common/index.ts","lineNumber":42,"sourceCode":"    is_web_worker(): boolean;\n    lookup_file(ptr: number, len: number): number;\n    read(handle: number, ptr: number, len: number, offset: number): number;\n    read_async(handle: number, ptr: number, len: number, offset: number, c: number);\n    write(handle: number, ptr: number, len: number, offset: number): number;\n    write_async(handle: number, ptr: number, len: number, offset: number, c: number);\n    sync(handle: number): number;\n    sync_async(handle: number, c: number);\n    truncate(handle: number, len: number): number;\n    truncate_async(handle: number, len: number, c: number);\n    size(handle: number): number;\n}\n\nfunction panicMain(name): never {\n    throw new Error(`method ${name} must be invoked only from the worker thread`);\n}\n\nfunction panicWorker(name): never {\n    throw new Error(`method ${name} must be invoked only from the main thread`);\n}\n\nfunction mainImports(worker: Worker, completeOpfs: (c: any, r: any) => void): BrowserImports {\n    return {\n        is_web_worker(): boolean {\n            return false;\n        },\n        write_async(handle, ptr, len, offset, c) {\n            writeFileAtWorker(worker, handle, ptr, len, offset)\n                .then(result => {\n                    completeOpfs(c, result);\n                }, err => {\n                    console.error('write_async', err);\n                    completeOpfs(c, -1);\n                });\n        },\n        sync_async(handle, c) {\n            syncFileAtWorker(worker, handle)","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/tursodatabase/turso/blob/244cde92a7df7f9b8b8b7a4075c35a12977e303e/bindings/javascript/packages/wasm-common/index.ts#L24-L60","documentation":"panicWorker() in wasm-common/index.ts is the mirror guard of panicMain: the worker-side import object routes methods that only the main thread may execute (async OPFS completion paths and friends) to this throw. If the worker-side shim is invoked on the main thread, the module/imports were wired to the wrong context - normally worker and main import sets are installed in their respective realms by setupMainThread/worker setup. The error therefore indicates main-thread code executing a worker-only import.","triggerScenarios":"Bundling both import sets into one context (e.g. a bundler collapsing the worker into the main chunk) so workerImports end up installed on the main thread; manually calling worker-side completion helpers (e.g. completeOpfs) from main-thread code; duplicated module instances where the worker shim registers in the main realm.","commonSituations":"Aggressive bundler settings (inlineWorker, single-file builds) merging worker and main code; copy-pasted worker bootstrap into a main-thread script; dev-server HMR re-evaluating the wasm-common module in the main realm.","solutions":["Use the package's official entry points so worker imports are only installed inside the spawned worker.","Disable worker inlining/single-file transforms for the turso worker chunk in your bundler config.","Never call worker-side helpers (completeOpfs, worker file ops) from application code; treat them as engine internals.","After HMR issues, do a full reload/rebuild - stale module instances can leave shims registered in the wrong realm."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"const inWorker =\n  typeof WorkerGlobalScope !== \"undefined\" &&\n  self instanceof WorkerGlobalScope;\nif (!inWorker) {\n  // never call worker-side IO/completion helpers here\n}","typeGuard":"const isMainThread = (): boolean =>\n  typeof WorkerGlobalScope === \"undefined\" ||\n  !(self instanceof WorkerGlobalScope);","tryCatchPattern":"try {\n  await operation();\n} catch (e) {\n  if (e instanceof Error && /invoked only from the main thread/.test(e.message)) {\n    // worker imports leaked into the main realm: fix bundler worker config\n  } else throw e;\n}","preventionTips":["Use official entry points; never import worker-side helpers into app code.","Disable single-file/inline-worker bundling for the turso worker chunk.","Full-reload after HMR weirdness to re-register shims in the right realm."],"tags":["wasm","opfs","threading","web-worker","bundler"],"backgroundTag":"wrong-thread-invocation","analyzedSha":"244cde92a7df7f9b8b8b7a4075c35a12977e303e","analyzedAt":"2026-08-20T07:02:18.389Z","contentChangedAt":"2026-08-20T07:02:18.389Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}