livestorejs/livestore

Improve error messages when using web adapter in Node.js environment

Open

#412 opened on Jul 7, 2025

View on GitHub
 (0 comments) (2 reactions) (0 assignees)TypeScript (128 forks)github user discovery
adapter:weberror-handlinghelp wanted

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-web uses 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! 🙂

Contributor guide