Improve error messages when using web adapter in Node.js environment
#412 opened on Jul 7, 2025
Repository metrics
- Stars
- (3,599 stars)
- PR merge metrics
- (PR metrics pending)
Description
Problem
When developers accidentally use @livestore/adapter-web in Node.js-like environments (Node.js, Bun, Deno), they get confusing WebAssembly memory errors instead of a helpful message about using the wrong adapter.
Current error:
Aborted(Cannot enlarge memory arrays to size 16977920 bytes (OOM).
Either (1) compile with -sINITIAL_MEMORY=X with X higher than the current value 16973824,
(2) compile with -sALLOW_MEMORY_GROWTH which allows increasing the size at runtime,
or (3) if you want malloc to return NULL (0) instead of this abort, compile with -sABORTING_MALLOC=0)
This leads developers to debug WebAssembly memory issues when they should just use @livestore/adapter-node.
Root Cause
@livestore/adapter-webuses WebAssembly SQLite with a 16.19 MB fixed memory limit- This limit is easily hit with moderate datasets (1500+ records)
- The error message suggests WebAssembly compilation fixes instead of proper adapter usage
- Affects Node.js, Bun, Deno, and other server-side JavaScript runtimes
Reproduction
// This triggers the confusing error in Node.js/Bun/Deno
import { makeInMemoryAdapter } from '@livestore/adapter-web'
import { createStorePromise } from '@livestore/livestore'
const adapter = makeInMemoryAdapter() // Should warn about server-side usage
const store = await createStorePromise({ schema, adapter, storeId: 'test' })
// Adding 1500+ records hits WebAssembly memory limit
Proposed Solution
1. Add environment detection warning
// In @livestore/adapter-web
function isServerSideEnvironment() {
return typeof process \!== 'undefined' && (
process.versions?.node || // Node.js
process.versions?.bun || // Bun
process.versions?.deno // Deno
)
}
if (isServerSideEnvironment()) {
console.warn(`⚠️ Using @livestore/adapter-web in a server-side environment may hit memory limits.
Consider @livestore/adapter-node for better performance and no memory limits.
Detected runtime: ${process.versions?.node ? 'Node.js' : process.versions?.bun ? 'Bun' : 'Deno'}`)
}
2. Enhance WebAssembly error messages
if (error.message.includes('Cannot enlarge memory arrays')) {
const runtime = process.versions?.node ? 'Node.js' :
process.versions?.bun ? 'Bun' :
process.versions?.deno ? 'Deno' : 'server-side'
throw new Error(`WebAssembly SQLite memory limit exceeded.
This often happens when using @livestore/adapter-web in ${runtime} environments.
Consider using @livestore/adapter-node instead for server-side usage.
Original error: ${error.message}`)
}
Benefits
- ✅ Faster debugging (minutes instead of hours)
- ✅ Better architecture guidance for all server-side runtimes
- ✅ Reduced support burden
- ✅ Clearer error messages across Node.js, Bun, and Deno
Context
This issue was discovered after extensive debugging of what appeared to be a WebAssembly memory configuration problem in Bun, but was actually just using the wrong adapter for the environment. The same issue would affect Node.js and Deno users.
Happy to contribute a PR if this approach looks good! 🙂