fix(memory): gracefully degrade when embedding provider is unregistered

xydt-tanshanshan · xydt-tanshanshan · commit df80fe739fdf · 2026-06-10T12:26:49.000+08:00
When a configured embedding provider (e.g. 'openai') has no registered adapter—typically because the provider plugin is not installed— ensureProviderInitialized() previously let the 'Unknown memory embedding provider' error propagate, crashing the CLI on . Now the error is caught and the manager gracefully degrades to FTS-only mode, setting providerUnavailableReason so that still works and shows the real problem instead of a stack trace. Refs #91778
diff --git a/extensions/memory-core/src/memory/manager.ts b/extensions/memory-core/src/memory/manager.ts
@@ -471,7 +471,22 @@ export class MemoryIndexManager extends MemoryManagerEmbeddingOps implements Mem
       // Clear the cached rejected promise so subsequent calls can retry
       // initialization instead of being permanently stuck with a stale failure.
       this.providerInitPromise = null;
-      throw err;
+      const message = formatErrorMessage(err);
+      const isUnknownProvider = message.startsWith("Unknown memory embedding provider:");
+      if (isUnknownProvider) {
+        // Gracefully degrade: the configured embedding provider plugin is not
+        // installed or not registered. Set FTS-only mode so the CLI and
+        // memory status still work instead of crashing.
+        this.applyProviderResult({
+          provider: null,
+          requestedProvider: this.requestedProvider,
+          providerUnavailableReason: message,
+        });
+        this.providerKey = this.computeProviderKey();
+        this.batch = this.resolveBatchConfig();
+      } else {
+        throw err;
+      }
     } finally {
       if (this.providerInitialized) {
         this.providerInitPromise = null;
diff --git a/extensions/memory-core/src/memory/manager.unknown-provider-degradation.test.ts b/extensions/memory-core/src/memory/manager.unknown-provider-degradation.test.ts
@@ -0,0 +1,105 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/memory-core-host-engine-foundation";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { closeAllMemorySearchManagers, getMemorySearchManager } from "./index.js";
+import type { MemoryIndexManager } from "./manager.js";
+import "./test-runtime-mocks.js";
+
+const createEmbeddingProviderMock = vi.hoisted(() =>
+  vi.fn(async () => {
+    throw new Error("Unknown memory embedding provider: nonexistent-provider");
+  }),
+);
+
+vi.mock("./embeddings.js", () => ({
+  createEmbeddingProvider: createEmbeddingProviderMock,
+  resolveEmbeddingProviderAdapterId: () => undefined,
+  resolveEmbeddingProviderAdapterTransport: () => "remote" as const,
+  resolveEmbeddingProviderFallbackModel: () => "fts-only",
+}));
+
+describe("memory manager unknown provider graceful degradation", () => {
+  let fixtureRoot = "";
+  let caseId = 0;
+  let workspaceDir = "";
+  let indexPath = "";
+  let manager: MemoryIndexManager | null = null;
+
+  beforeAll(async () => {
+    fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-mem-unknown-provider-"));
+  });
+
+  beforeEach(async () => {
+    createEmbeddingProviderMock.mockClear();
+    workspaceDir = path.join(fixtureRoot, `case-${caseId++}`);
+    await fs.mkdir(path.join(workspaceDir, "memory"), { recursive: true });
+    await fs.writeFile(path.join(workspaceDir, "MEMORY.md"), "Test memory note.\n\nAlpha topic.");
+    indexPath = path.join(workspaceDir, "index.sqlite");
+  });
+
+  afterEach(async () => {
+    if (manager) {
+      await manager.close();
+      manager = null;
+    }
+    await closeAllMemorySearchManagers();
+  });
+
+  afterAll(async () => {
+    await closeAllMemorySearchManagers();
+    if (fixtureRoot) {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
+  async function createManager(
+    params: { provider?: string; vectorEnabled?: boolean } = {},
+  ): Promise<MemoryIndexManager> {
+    const store =
+      params.vectorEnabled === undefined
+        ? { path: indexPath }
+        : { path: indexPath, vector: { enabled: params.vectorEnabled } };
+    const cfg = {
+      memory: { backend: "builtin" },
+      agents: {
+        defaults: {
+          workspace: workspaceDir,
+          memorySearch: {
+            provider: params.provider ?? "nonexistent-provider",
+            model: "",
+            store,
+            cache: { enabled: false },
+            sync: { watch: false, onSessionStart: false, onSearch: false },
+          },
+        },
+        list: [{ id: "main", default: true }],
+      },
+    } as OpenClawConfig;
+    const result = await getMemorySearchManager({ cfg, agentId: "main" });
+    if (!result.manager) {
+      throw new Error(result.error ?? "manager missing");
+    }
+    manager = result.manager as unknown as MemoryIndexManager;
+    return manager;
+  }
+
+  it("does not crash on probeEmbeddingAvailability when provider is unknown", async () => {
+    const memoryManager = await createManager();
+
+    const probeResult = await memoryManager.probeEmbeddingAvailability();
+    expect(probeResult.ok).toBe(false);
+    expect(probeResult.error).toContain("Unknown memory embedding provider");
+  });
+
+  it("reports fts-only lifecycle after probe when provider is unknown", async () => {
+    const memoryManager = await createManager();
+
+    await memoryManager.probeEmbeddingAvailability();
+
+    const status = memoryManager.status();
+    expect(status.custom?.providerState?.mode).toBe("fts-only");
+    expect(status.custom?.providerState?.reason).toContain("Unknown memory embedding provider");
+  });
+});
