TencentCloud/TencentDB-Agent-Memory · error · EmbeddingNotReadyError

Local embedding model initialization failed: ${this.initErro

Error message

Local embedding model initialization failed: ${this.initError?.message ?? "unknown error"}. Call startWarmup() to retry.

What it means

The local embedding provider (node-llama-cpp, embeddinggemma-300m) failed to initialize during startWarmup(); initState is 'failed' with the underlying reason stored in initError. embed()/embedBatch() call assertReady() which throws EmbeddingNotReadyError instead of proceeding without a model. The message instructs callers to call startWarmup() to retry initialization.

Source

Thrown at MemoryCore/src/core/store/embedding.ts:284

        // best-effort cleanup
      }
      this.embeddingContext = null;
      this.initPromise = null;
      this.initState = "idle";
      this.initError = null;
      this.logger?.info(`${TAG} Local embedding resources released`);
    }
  }

  /**
   * Assert the model is ready. Throws EmbeddingNotReadyError if not.
   */
  private assertReady(): void {
    if (this.initState === "ready" && this.embeddingContext) {
      return;
    }
    if (this.initState === "failed") {
      throw new EmbeddingNotReadyError(
        `Local embedding model initialization failed: ${this.initError?.message ?? "unknown error"}. ` +
        `Call startWarmup() to retry.`,
      );
    }
    if (this.initState === "initializing") {
      throw new EmbeddingNotReadyError(
        "Local embedding model is still loading (download/initialization in progress). Please try again later.",
      );
    }
    // "idle" — startWarmup() was never called
    throw new EmbeddingNotReadyError(
      "Local embedding model warmup has not been started. Call startWarmup() first.",
    );
  }

  /**
   * Truncate input text to stay within the model's context window.
   * embeddinggemma-300m has a 256-token limit; we use a character-based

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Call startWarmup() again to retry model initialization (after fixing the root cause).
2. Check the wrapped initError message in logs for the underlying failure (download error, missing model file, native binding load failure, OOM) and fix it.
3. Verify network access / model cache path / node-llama-cpp installation, then restart the service or recreate the embedder instance.
4. If local inference is not viable in the environment, switch to a remote embedding provider.

Example fix

// before
const vec = await embedder.embed(text); // throws if warmup failed
// after
try {
  const vec = await embedder.embed(text);
} catch (e) {
  if (e instanceof EmbeddingNotReadyError) {
    await embedder.startWarmup(); // retry initialization
    const vec = await embedder.embed(text);
  }
}

function isEmbeddingReady(e: { initState?: string }): boolean {
  return e.initState === "ready";
}
// or catch-based narrowing:
function isEmbeddingNotReadyError(e: unknown): e is EmbeddingNotReadyError {
  return e instanceof EmbeddingNotReadyError;
}

try {
  return await embedder.embed(text);
} catch (e) {
  if (isEmbeddingNotReadyError(e) && /initialization failed/.test(e.message)) {
    await embedder.startWarmup(); // fix root cause first; retry once
    return await embedder.embed(text);
  }
  throw e;
}

When it happens

Trigger: Calling embed() or embedBatch() after warmup previously failed — e.g. the GGUF model download failed, the model file is missing/corrupt, node-llama-cpp native bindings are unavailable, or there is insufficient memory/GPU. Any later embed call on the failed instance throws this until startWarmup() succeeds again.

Common situations: Offline or restricted-network environment blocked the model download at startup; wrong or corrupt model path in config; missing native llama.cpp binaries for the platform/architecture; OOM on low-memory hosts; after close() reset plus a failed re-warmup.

Related errors

• Local embedding model warmup has not been started. Call star
• Local embedding model is still loading (download/initializat
• EmbeddingService: apiKey is required for remote provider
• EmbeddingService: baseUrl is required for remote provider
• EmbeddingService: model is required for remote provider

AI-assisted analysis of TencentCloud/TencentDB-Agent-Memory@3efcd317b8 (2026-09-01). Data as JSON: /api/errors/ba32471138e52218. Report an issue: GitHub.