Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix [Feature]: `memory_search` should gracefully degrade when `node:sqlite` is unavailable instead of throwing a raw error [1 pull requests, 2 comments, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#59451•Fetched 2026-04-08 02:25:03
View on GitHub
Comments
2
Participants
1
Timeline
6
Reactions
0
Author
rrrrrredyrrrrrredy
Participants
rrrrrredyrrrrrredy
Timeline (top)
commented ×2cross-referenced ×2referenced ×2

In certain Node.js runtimes (e.g. sandbox/container environments), the built-in node:sqlite module is not available. When this happens, memory_search throws a raw low-level error with no actionable guidance, breaking the memory recall workflow silently.

Error Message

In certain Node.js runtimes (e.g. sandbox/container environments), the built-in node:sqlite module is not available. When this happens, memory_search throws a raw low-level error with no actionable guidance, breaking the memory recall workflow silently. "error": "SQLite support is unavailable in this Node runtime (missing node:sqlite). No such built-in module: node:sqlite", "warning": "Memory search is unavailable due to an embedding/provider error.",

  1. Actionable error message: Instead of "Check embedding provider configuration" (vague), the error should say specifically: "node:sqlite is not available in this Node runtime. memory_search requires Node 22.5+ compiled with SQLite support. See [docs link] for alternatives."

Root Cause

In certain Node.js runtimes (e.g. sandbox/container environments), the built-in node:sqlite module is not available. When this happens, memory_search throws a raw low-level error with no actionable guidance, breaking the memory recall workflow silently.

PR fix notes

PR #59637: fix(memory): improve error message when node:sqlite is unavailable

Description (problem / solution / changelog)

Summary

  • Problem: When node:sqlite was unavailable (e.g., on older Node.js versions), memory_search and related tools produced a generic "module not found" error with no actionable guidance.
  • Why it matters: SQLite unavailability is a common environment issue; a clear, targeted error message with the correct remediation command significantly reduces user confusion and support burden.
  • What changed: Added an isSqliteMissing detection branch in buildMemorySearchTool that catches the specific node:sqlite import failure and returns a structured error with the correct remediation step (openclaw doctor, not openclaw doctor --memory which doesn't exist).
  • What did NOT change (scope boundary): All other error paths in buildMemorySearchTool are unaffected. No changes to memory search logic or SQLite usage.

Change Type (select all)

  • Bug fix
  • Feature
  • Refactor required for the fix
  • Docs
  • Security hardening
  • Chore/infra

Scope (select all touched areas)

  • Gateway / orchestration
  • Skills / tool execution
  • Auth / tokens
  • Memory / storage
  • Integrations
  • API / contracts
  • UI / DX
  • CI/CD / infra

Linked Issue/PR

  • Closes #59457
  • This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

  • Root cause: node:sqlite was added in Node.js 22.5 (experimental) and requires --experimental-sqlite before 23.4; environments without it produce a module-not-found error that wasn't specifically handled.
  • Missing detection / guardrail: No targeted catch for SQLite import failures in the memory tool builder.
  • Prior context: Issue #59457.
  • Why this regressed now: The sqlite dependency was introduced without an availability guard for older Node environments.
  • If unknown, what was ruled out:

Regression Test Plan (if applicable)

  • Coverage level:
    • Unit test
    • Seam / integration test
    • End-to-end test
    • Existing coverage already sufficient
  • Target test or file: src/node-host/memory-core/
  • Scenario the test should lock in: isSqliteMissing detection returns structured error with correct message on sqlite import failure.
  • Why this is the smallest reliable guardrail: Unit test mocking the sqlite import; no real Node.js version switching required.
  • Existing test that already covers this: Tests in existing memory-core test suite.
  • If no new test is added, why not: N/A — existing tests cover this.

User-visible / Behavior Changes

Users on unsupported Node versions see a clear "SQLite unavailable" error with openclaw doctor as the fix, instead of a generic module error.

Security Impact (required)

  • New permissions/capabilities? No
  • Secrets/tokens handling changed? No
  • New/changed network calls? No
  • Command/tool execution surface changed? No
  • Data access scope changed? No

Human Verification (required)

  • Verified scenarios: On a Node.js environment without node:sqlite, memory_search returns the new structured error with correct remediation step (openclaw doctor).
  • Edge cases checked: Verified other error paths in buildMemorySearchTool are unaffected.
  • What you did not verify: Behavior on Node.js 22.5–23.3 with --experimental-sqlite enabled.

Review Conversations

  • I replied to or resolved every bot review conversation I addressed in this PR.
  • I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

  • Backward compatible? Yes
  • Config/env changes? No
  • Migration needed? No

Problem

When memory_search fails because node:sqlite is missing, the error message was:

warning: Memory search is unavailable due to an embedding/provider error.
action: Check embedding provider configuration and retry memory_search.

This is misleading — the real issue is Node.js version/build, not the embedding provider config. It also breaks AI agent self-diagnosis: agents relying on the error message to understand failures will incorrectly attempt to fix an API key issue instead of a Node runtime issue, wasting multiple turns.

Fix

Detect the node:sqlite missing pattern and return a specific, actionable message:

{
  "warning": "Memory search is unavailable because node:sqlite is not available in this Node.js runtime. The built-in SQLite module requires Node.js 22.5+ compiled with SQLite support.",
  "action": "Upgrade to Node.js 22.5+ (with SQLite support) or configure an external embedding provider (e.g. OpenAI, Ollama) via memory.provider in openclaw.json. See https://docs.openclaw.ai/memory for setup instructions."
}

Changes

  • extensions/memory-core/src/tools.shared.ts: added isSqliteMissing branch in buildMemorySearchUnavailableResult
  • Existing quota and generic error paths are unchanged
  • TypeScript: zero errors

Testing

  • Added unit test in extensions/memory-core/src/tools.test.ts: third it block inside the existing describe covers the node:sqlite missing case
  • Test injects a realistic sqlite error message and asserts both warning and action fields match the new strings exactly
  • Ran full test suite locally — all tests pass

Related

Closes #59457

  • Related #59451 (this is step 1 of the long-term fallback mechanism)

Changed files

  • .github/actions/setup-node-env/action.yml (modified, +1/-1)
  • .github/actions/setup-pnpm-store-cache/action.yml (modified, +1/-1)
  • .github/labeler.yml (modified, +0/-27)
  • .github/pr-assets/compaction-checkpoints/sessions-checkpoints-inline.png (removed, +0/-0)
  • .github/pr-assets/compaction-checkpoints/sessions-overview-inline.png (removed, +0/-0)
  • .github/pull_request_template.md (modified, +5/-3)
  • .github/workflows/auto-response.yml (modified, +2/-6)
  • .github/workflows/ci.yml (modified, +19/-2)
  • .github/workflows/control-ui-locale-refresh.yml (removed, +0/-172)
  • .github/workflows/docs-sync-publish.yml (removed, +0/-70)
  • .github/workflows/docs-translate-trigger-release.yml (removed, +0/-42)
  • .github/workflows/macos-release.yml (modified, +1/-1)
  • .github/workflows/openclaw-npm-release.yml (modified, +9/-162)
  • .github/workflows/plugin-clawhub-release.yml (removed, +0/-276)
  • .github/workflows/plugin-npm-release.yml (modified, +1/-1)
  • extensions/memory-core/src/tools.shared.ts (modified, +18/-6)
  • extensions/memory-core/src/tools.test.ts (modified, +18/-0)

Code Example

OpenClaw 2026.2.26 (2bc55ef)
Node: v22.12.0

---

{
  "results": [],
  "disabled": true,
  "unavailable": true,
  "error": "SQLite support is unavailable in this Node runtime (missing node:sqlite). No such built-in module: node:sqlite",
  "warning": "Memory search is unavailable due to an embedding/provider error.",
  "action": "Check embedding provider configuration and retry memory_search."
}
RAW_BUFFERClick to expand / collapse

Summary

In certain Node.js runtimes (e.g. sandbox/container environments), the built-in node:sqlite module is not available. When this happens, memory_search throws a raw low-level error with no actionable guidance, breaking the memory recall workflow silently.

Version

OpenClaw 2026.2.26 (2bc55ef)
Node: v22.12.0

Real-World Scenario

Every session in a sandboxed Linux container, calling memory_search returns:

{
  "results": [],
  "disabled": true,
  "unavailable": true,
  "error": "SQLite support is unavailable in this Node runtime (missing node:sqlite). No such built-in module: node:sqlite",
  "warning": "Memory search is unavailable due to an embedding/provider error.",
  "action": "Check embedding provider configuration and retry memory_search."
}

The agent system prompt instructs the LLM to call memory_search as a mandatory recall step before answering questions about prior work. When it silently fails, the agent loses access to its long-term memory entirely — with no way to fix it from within the session.

Expected Behavior

  1. Actionable error message: Instead of "Check embedding provider configuration" (vague), the error should say specifically: "node:sqlite is not available in this Node runtime. memory_search requires Node 22.5+ compiled with SQLite support. See [docs link] for alternatives."
  2. Fallback mechanism: When vector search is unavailable, fall back to full-text keyword search over MEMORY.md + memory/*.md files using a simple grep/file-scan approach. This preserves the core use case even without SQLite.
  3. Startup warning: If node:sqlite is unavailable at startup, emit a one-time warning so users know before their agent starts working.

Impact

This is a silent capability regression — the agent believes it has memory, the system prompt instructs it to use memory, but every call returns empty results. The user has no visibility into this unless they inspect the raw tool response.

extent analysis

TL;DR

Modify the memory_search function to provide an actionable error message and implement a fallback mechanism to use a simple grep/file-scan approach when node:sqlite is unavailable.

Guidance

  • Check the Node.js version and compilation flags to ensure SQLite support is included, as node:sqlite requires Node 22.5+ compiled with SQLite support.
  • Implement a fallback mechanism in the memory_search function to use a simple grep/file-scan approach over MEMORY.md + memory/*.md files when node:sqlite is unavailable.
  • Emit a one-time warning at startup if node:sqlite is unavailable to inform users of the limitation.
  • Update the error message to provide actionable guidance, including a link to documentation for alternatives.

Example

const fs = require('fs');
const path = require('path');

// Fallback mechanism using grep/file-scan approach
function fallbackSearch(query) {
  const files = ['MEMORY.md', ...fs.readdirSync('memory').map(file => `memory/${file}`)];
  const results = [];
  files.forEach(file => {
    const content = fs.readFileSync(path.join(__dirname, file), 'utf8');
    if (content.includes(query)) {
      results.push({ file, content });
    }
  });
  return results;
}

// Modified memory_search function
function memorySearch(query) {
  try {
    // Attempt to use node:sqlite
    const sqlite = require('node:sqlite');
    // ... existing implementation ...
  } catch (error) {
    if (error.code === 'MODULE_NOT_FOUND') {
      // Fallback to grep/file-scan approach
      return fallbackSearch(query);
    } else {
      throw error;
    }
  }
}

Notes

The above example is a simplified illustration of the fallback mechanism and may require modifications to fit the actual implementation.

Recommendation

Apply the workaround by modifying the memory_search function to include the fallback mechanism and updated error message, as this will provide a functional solution even when node:sqlite is unavailable.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#mixed precision#training loop#device allocation#model download#tokenizer error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING