Summary

When memory_search fails due to a missing node:sqlite module, it returns a raw low-level error object. The error message is not actionable, and the action field gives generic advice that does not help users resolve the issue.

Affects: all users running OpenClaw without node:sqlite support (Node builds without SQLite, minimal Docker images, some cloud sandboxes).

Actual Error Response (verbatim)

{
  "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."
}

Problems With Current Response

1. action is wrong: "Check embedding provider configuration" is misleading. The actual issue is Node runtime compatibility, not embedding provider config.
2. No Node version information: The error does not tell users what Node version is required or whether the current version supports node:sqlite.
3. Conflates two different problems: "embedding/provider error" implies an API key or network issue. Missing node:sqlite is a Node build/runtime issue �� completely different root cause.
4. Breaks AI agent self-diagnosis: OpenClaw is often used with AI agents that rely on tool response messages to understand failures. The current "Check embedding provider configuration" message causes agents to incorrectly attempt to fix an API key issue instead of a Node runtime issue, wasting multiple turns before failing.

Data

Observed on: Node v22.12.0 in a Linux sandbox environment. According to Node.js docs, node:sqlite was stabilized in Node 22.5.0 but requires the Node binary to be compiled with SQLite support �� which is not guaranteed in all environments (e.g. minimal Docker images, some cloud sandboxes).

Proposed Improvement

Return a more actionable error:

{
  "results": [],
  "disabled": true,
  "unavailable": true,
  "error": "node:sqlite module is not available in this Node.js runtime.",
  "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."
}

Additionally, consider emitting a one-time startup warning when node:sqlite is unavailable, so users know upfront that memory search is disabled before they rely on it.

Related

• [Feature]: Add file-based fallback search when node:sqlite is unavailable #59451 (longer-term fallback mechanism)
• Active fix PR: fix(memory): improve error message when node:sqlite is unavailable #69199

Suggested labels: bug, cli, ux, memory

Related: #69199

Note: This bug also breaks AI agent self-diagnosis �� the misleading error message directs agents toward incorrect remediation paths, compounding the impact beyond individual users.