{"record":{"id":"81eac7eb7956c7d7","repo":"perspective-dev/perspective","slug":"missing-perspective-client-wasm-81eac7","errorCode":null,"errorMessage":"Missing perspective-client.wasm","messagePattern":"Missing perspective-client\\.wasm","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"rust/perspective-js/src/ts/virtual_servers/duckdb.ts","lineNumber":278,"sourceCode":"        throw error;\n    }\n}\n\n/**\n * An implementation of Perspective's Virtual Server for `@duckdb/duckdb-wasm`.\n */\nexport class DuckDBHandler implements perspective.VirtualServerHandler {\n    private db: duckdb.AsyncDuckDBConnection;\n    private sqlBuilder: perspective.GenericSQLVirtualServerModel;\n    constructor(db: duckdb.AsyncDuckDBConnection, mod?: typeof perspective) {\n        if (!mod) {\n            if (customElements) {\n                const viewer_class: any =\n                    customElements.get(\"perspective-viewer\");\n                if (viewer_class) {\n                    mod = viewer_class.__wasm_module__;\n                } else {\n                    throw new Error(\"Missing perspective-client.wasm\");\n                }\n            } else {\n            }\n        }\n\n        this.db = db;\n        this.sqlBuilder = new mod!.GenericSQLVirtualServerModel({\n            column_separator: \"|\",\n            like_escape_clause: \"\\\\\",\n            regex_fn: \"regexp_matches\",\n        });\n    }\n\n    getFeatures(): perspective.Features {\n        return {\n            group_by: true,\n            split_by: true,\n            sort: true,","sourceCodeStart":260,"sourceCodeEnd":296,"githubUrl":"https://github.com/perspective-dev/perspective/blob/11c8238c0c9c0b9e490b5a6a2dc277afad1e980a/rust/perspective-js/src/ts/virtual_servers/duckdb.ts#L260-L296","documentation":"The DuckDBServer virtual server requires the perspective WASM client module (perspective-client.wasm) to execute DuckDB in WebAssembly. The constructor retrieves the module from the registered `<perspective-viewer>` custom element's `__wasm_module__` property. If the element is registered but the module was never attached, the constructor throws this error.","triggerScenarios":"Constructing a DuckDBServer while `customElements` is defined, `customElements.get(\"perspective-viewer\")` resolves to a registered class lacking `__wasm_module__` — the viewer web component was registered without its WASM payload being fetched/initialized.","commonSituations":"Registering the viewer component without awaiting its WASM init; version mismatch between @finos/perspective-viewer and perspective-js so `__wasm_module__` is never set; running under a test harness or polyfill that registers a placeholder `perspective-viewer` element; bundler config stripping the WASM asset so initialization silently no-ops.","solutions":["Import and fully initialize @finos/perspective-viewer (await its init/load of perspective-client.wasm) before constructing DuckDBServer.","Align versions of @finos/perspective-viewer and perspective-js (same release) and reinstall node_modules.","Manually fetch perspective-client.wasm and set it on the viewer class: `customElements.get(\"perspective-viewer\").__wasm_module__ = mod;`.","Confirm your bundler (webpack/vite) is configured to emit and load the .wasm asset so viewer init actually completes."],"exampleFix":"// before\nconst server = new DuckDBServer(db); // viewer registered but wasm never attached\n\n// after\nawait import(\"@finos/perspective-viewer\");\nawait customElements.whenDefined(\"perspective-viewer\");\nif (!customElements.get(\"perspective-viewer\").__wasm_module__) {\n  const mod = await WebAssembly.compileStreaming(fetch(\"perspective-client.wasm\"));\n  customElements.get(\"perspective-viewer\").__wasm_module__ = mod;\n}\nconst server = new DuckDBServer(db);","handlingStrategy":"validation","validationCode":"async function ensureDuckDBServerReady() {\n  await customElements.whenDefined(\"perspective-viewer\");\n  const viewer = customElements.get(\"perspective-viewer\");\n  if (!viewer || !viewer.__wasm_module__) {\n    throw new Error(\"perspective WASM not attached; await viewer init first\");\n  }\n}","typeGuard":"function viewerHasWasm(el: unknown): el is (new () => HTMLElement) & { __wasm_module__: WebAssembly.Module } {\n  return typeof el === 'function' && (el as any).__wasm_module__ != null;\n}","tryCatchPattern":"try {\n  const server = new DuckDBServer(db);\n} catch (e) {\n  if (e.message === \"Missing perspective-client.wasm\") {\n    await loadPerspectiveViewerWasm();\n    const server = new DuckDBServer(db); // retry once after init\n  } else throw e;\n}","preventionTips":["Initialize the perspective-viewer component (which fetches perspective-client.wasm) before any DuckDBServer construction.","Pin matching versions of perspective packages and verify WASM assets in your bundler output.","In tests, register the real viewer element, not a stub, or bypass the customElements path."],"tags":["webassembly","initialization","custom-elements","duckdb"],"backgroundTag":"module-init-failed","analyzedSha":"11c8238c0c9c0b9e490b5a6a2dc277afad1e980a","analyzedAt":"2026-09-09T00:35:19.377Z","contentChangedAt":"2026-09-09T00:35:19.377Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}