{"record":{"id":"ba32471138e52218","repo":"TencentCloud/TencentDB-Agent-Memory","slug":"local-embedding-model-initialization-failed-thi","errorCode":null,"errorMessage":"Local embedding model initialization failed: ${this.initError?.message ?? \"unknown error\"}. Call startWarmup() to retry.","messagePattern":"Local embedding model initialization failed: (.+?)\\. Call startWarmup\\(\\) to retry\\.","errorType":"exception","errorClass":"EmbeddingNotReadyError","httpStatus":null,"severity":"error","filePath":"MemoryCore/src/core/store/embedding.ts","lineNumber":284,"sourceCode":"        // best-effort cleanup\n      }\n      this.embeddingContext = null;\n      this.initPromise = null;\n      this.initState = \"idle\";\n      this.initError = null;\n      this.logger?.info(`${TAG} Local embedding resources released`);\n    }\n  }\n\n  /**\n   * Assert the model is ready. Throws EmbeddingNotReadyError if not.\n   */\n  private assertReady(): void {\n    if (this.initState === \"ready\" && this.embeddingContext) {\n      return;\n    }\n    if (this.initState === \"failed\") {\n      throw new EmbeddingNotReadyError(\n        `Local embedding model initialization failed: ${this.initError?.message ?? \"unknown error\"}. ` +\n        `Call startWarmup() to retry.`,\n      );\n    }\n    if (this.initState === \"initializing\") {\n      throw new EmbeddingNotReadyError(\n        \"Local embedding model is still loading (download/initialization in progress). Please try again later.\",\n      );\n    }\n    // \"idle\" — startWarmup() was never called\n    throw new EmbeddingNotReadyError(\n      \"Local embedding model warmup has not been started. Call startWarmup() first.\",\n    );\n  }\n\n  /**\n   * Truncate input text to stay within the model's context window.\n   * embeddinggemma-300m has a 256-token limit; we use a character-based","sourceCodeStart":266,"sourceCodeEnd":302,"githubUrl":"https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/3efcd317b84146d6a08518ac0f7ee7c8a8d200ec/MemoryCore/src/core/store/embedding.ts#L266-L302","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Call startWarmup() again to retry model initialization (after fixing the root cause).","Check the wrapped initError message in logs for the underlying failure (download error, missing model file, native binding load failure, OOM) and fix it.","Verify network access / model cache path / node-llama-cpp installation, then restart the service or recreate the embedder instance.","If local inference is not viable in the environment, switch to a remote embedding provider."],"exampleFix":"// before\nconst vec = await embedder.embed(text); // throws if warmup failed\n// after\ntry {\n  const vec = await embedder.embed(text);\n} catch (e) {\n  if (e instanceof EmbeddingNotReadyError) {\n    await embedder.startWarmup(); // retry initialization\n    const vec = await embedder.embed(text);\n  }\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":"function isEmbeddingReady(e: { initState?: string }): boolean {\n  return e.initState === \"ready\";\n}\n// or catch-based narrowing:\nfunction isEmbeddingNotReadyError(e: unknown): e is EmbeddingNotReadyError {\n  return e instanceof EmbeddingNotReadyError;\n}","tryCatchPattern":"try {\n  return await embedder.embed(text);\n} catch (e) {\n  if (isEmbeddingNotReadyError(e) && /initialization failed/.test(e.message)) {\n    await embedder.startWarmup(); // fix root cause first; retry once\n    return await embedder.embed(text);\n  }\n  throw e;\n}","preventionTips":["Run startWarmup() at startup and alert on its failure before serving traffic.","Log the underlying initError (download, model path, native bindings, memory) and monitor it.","Pre-download/cache the model artifact in the deployment image to remove network dependency.","Configure a fallback embedding provider for environments where local init cannot succeed."],"tags":["embedding","initialization-failed","model-loading","local-inference"],"backgroundTag":"embedding-model-not-ready","analyzedSha":"3efcd317b84146d6a08518ac0f7ee7c8a8d200ec","analyzedAt":"2026-09-01T05:44:22.276Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}