{"record":{"id":"78260a3d8a944c85","repo":"rohitg00/agentmemory","slug":"install-huggingface-transformers-for-local-embedd","errorCode":null,"errorMessage":"Install @huggingface/transformers for local embeddings: npm install @huggingface/transformers","messagePattern":"Install @huggingface/transformers for local embeddings: npm install @huggingface/transformers","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/providers/embedding/local.ts","lineNumber":34,"sourceCode":"  }\n\n  async embedBatch(texts: string[]): Promise<Float32Array[]> {\n    const extractor = await this.getExtractor();\n    const output = await extractor(texts, {\n      pooling: \"mean\",\n      normalize: true,\n    });\n    return output.tolist().map((v) => new Float32Array(v));\n  }\n\n  private async getExtractor() {\n    if (this.extractor) return this.extractor;\n    let transformers: typeof import(\"@huggingface/transformers\");\n    try {\n      transformers = await import(\"@huggingface/transformers\");\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code === \"ERR_MODULE_NOT_FOUND\") {\n        throw new Error(\n          \"Install @huggingface/transformers for local embeddings: npm install @huggingface/transformers\",\n        );\n      }\n      throw err;\n    }\n    this.extractor = (await transformers.pipeline(\n      \"feature-extraction\",\n      \"Xenova/all-MiniLM-L6-v2\",\n      { dtype: \"q8\" },\n    )) as FeatureExtractor;\n    return this.extractor;\n  }\n}\n","sourceCodeStart":16,"sourceCodeEnd":48,"githubUrl":"https://github.com/rohitg00/agentmemory/blob/e04ba88819c365c9acf9d6661ea802143e728bd6/src/providers/embedding/local.ts#L16-L48","documentation":"LocalEmbeddingProvider relies on the optional peer dependency @huggingface/transformers to run on-device embedding models. The package is intentionally not bundled, so getExtractor() attempts a dynamic import and, when Node reports ERR_MODULE_NOT_FOUND, throws this actionable install message instead of an opaque module-not-found stack.","triggerScenarios":"Selecting the 'local' embedding provider (LocalEmbeddingProvider) and calling embed()/embedBatch() for the first time (lazy extractor initialization) in a project where @huggingface/transformers is not installed.","commonSituations":"Fresh install of agentmemory without optional dependencies; CI image stripped of heavy ML deps; user switched AGENTMEMORY embedding provider to 'local' without adding the dependency; pnpm/yarn hoisting differences leaving the optional peer unresolved.","solutions":["Run: npm install @huggingface/transformers (or pnpm add / yarn add equivalent)","Pin a compatible version if the installed transformers API differs (pipeline export moved across majors)","If local inference is not actually wanted, configure a remote provider (openai/openrouter/voyage) instead"],"exampleFix":"// before\nnpm install\n// after (add the optional local-embeddings dependency)\nnpm install @huggingface/transformers","handlingStrategy":"validation","validationCode":"let localEmbeddingsAvailable = false;\ntry {\n  await import('@huggingface/transformers');\n  localEmbeddingsAvailable = true;\n} catch { localEmbeddingsAvailable = false; }\n// before choosing provider type 'local', check localEmbeddingsAvailable","typeGuard":"function canUseLocalEmbeddings(m: unknown): m is { pipeline: unknown } {\n  return !!m && typeof (m as any).pipeline === 'function';\n}","tryCatchPattern":"try {\n  return await localProvider.embed(text);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('Install @huggingface/transformers')) {\n    console.error('Local embeddings need: npm install @huggingface/transformers');\n    return fallbackProvider.embed(text);\n  }\n  throw err;\n}","preventionTips":["Install @huggingface/transformers at project setup if any config may use the local provider","Document optional deps in your deployment/CI image build","Gate local-provider selection behind a capability check at startup","Prefer remote providers in size-constrained environments"],"tags":["embedding","missing-dependency","local-inference"],"backgroundTag":"missing-optional-dependency","analyzedSha":"e04ba88819c365c9acf9d6661ea802143e728bd6","analyzedAt":"2026-08-30T01:07:40.754Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}