{"record":{"id":"3ec2ac0b7540d7ce","repo":"abhigyanpatwari/GitNexus","slug":"failed-to-download-embedding-model-errmsg-3ec2ac","errorCode":null,"errorMessage":"Failed to download embedding model: ${errMsg}\n  ${endpointHint}","messagePattern":"Failed to download embedding model: (.+?)\n  (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"gitnexus/src/mcp/core/embedder.ts","lineNumber":154,"sourceCode":"            restoreStdout();\n            process.stderr.write = realStderrWrite;\n          }\n          logger.info({ device }, 'GitNexus: Embedding model loaded');\n          return embedderInstance!;\n        } catch (deviceError) {\n          // Network errors and circuit-open errors are not device-specific —\n          // they will fail the same way on every device. Rethrow immediately\n          // with actionable HF_ENDPOINT guidance rather than silently falling\n          // back to the next device.\n          const errMsg = deviceError instanceof Error ? deviceError.message : String(deviceError);\n          if (isHfDownloadFailure(errMsg)) {\n            const endpointHint = process.env.HF_ENDPOINT\n              ? `The configured endpoint (${process.env.HF_ENDPOINT}) may be unreachable.`\n              : `huggingface.co may be unreachable from your network.\\n` +\n                `  Set HF_ENDPOINT to a mirror and retry:\\n` +\n                `    HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings\\n` +\n                `    (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings)`;\n            throw new Error(`Failed to download embedding model: ${errMsg}\\n  ${endpointHint}`);\n          }\n          if (device === 'cpu') throw new Error('Failed to load embedding model');\n        }\n      }\n\n      throw new Error('No suitable device found');\n    } catch (error) {\n      isInitializing = false;\n      initPromise = null;\n      embedderInstance = null;\n      throw error;\n    } finally {\n      isInitializing = false;\n    }\n  })();\n\n  return initPromise;\n};","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/aac7515d2a8c50a1f8f923c6fb77218b333560d6/gitnexus/src/mcp/core/embedder.ts#L136-L172","documentation":"While initEmbedder probes devices, a device failure whose message matches isHfDownloadFailure is treated as device-independent network trouble and rethrown immediately with the underlying error plus an HF_ENDPOINT hint, rather than silently trying the next device. It means the embedding model could not be fetched from huggingface.co (or the configured HF_ENDPOINT mirror).","triggerScenarios":"First run of `analyze --embeddings` or MCP semantic search with no model cached, on a network where huggingface.co (or a configured HF_ENDPOINT) is unreachable: GFW-style blocking, corporate firewalls, TLS interception, proxy misconfiguration, or an HF outage. Also fires when a custom HF_ENDPOINT is itself down.","commonSituations":"Developers in regions requiring HF mirrors; CI runners without egress to huggingface.co; a wrong/expired HF_ENDPOINT pointing at a dead internal mirror; laptops on guest networks.","solutions":["Set HF_ENDPOINT to a mirror and retry: `HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings` (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings).","Fix egress: allow huggingface.co (and cdn) through the proxy/firewall, or set HTTPS_PROXY correctly for the Node process.","Pre-download the model once on a machine with access and share the cache via HF_HOME.","Switch to HTTP embeddings: set GITNEXUS_EMBEDDING_URL + GITNEXUS_EMBEDDING_MODEL at an OpenAI-compatible endpoint so no HF download is needed."],"exampleFix":"# before: direct huggingface.co blocked\n$ gitnexus analyze --embeddings\n# → Failed to download embedding model: ...\n\n# after: use the HF mirror endpoint\n$ HF_ENDPOINT=https://hf-mirror.com gitnexus analyze --embeddings","handlingStrategy":"retry","validationCode":"// Check endpoint reachability before the first embeddings run\nasync function hfEndpointReachable(): Promise<boolean> {\n  const base = process.env.HF_ENDPOINT ?? 'https://huggingface.co';\n  try {\n    const res = await fetch(`${base}/transformers.js/all-MiniLM-L6-v2/resolve/latest/config.json`, {\n      method: 'HEAD',\n      signal: AbortSignal.timeout(5000),\n    });\n    return res.ok;\n  } catch {\n    return false;\n  }\n}","typeGuard":null,"tryCatchPattern":"let lastErr: unknown;\nfor (let attempt = 0; attempt < 3; attempt++) {\n  try {\n    return await runAnalyze({ embeddings: true });\n  } catch (err) {\n    const msg = err instanceof Error ? err.message : String(err);\n    if (!msg.includes('Failed to download embedding model')) throw err;\n    lastErr = err;\n    await sleep(2 ** attempt * 1000); // network issues are often transient; mirror env persists\n  }\n}\nthrow lastErr;","preventionTips":["Set HF_ENDPOINT=https://hf-mirror.com in networks with restricted huggingface.co access.","Pre-warm the model cache once per image/host (HF_HOME) so CI never downloads at runtime.","Allow-list huggingface.co and its CDN in corporate proxies.","Prefer GITNEXUS_EMBEDDING_URL HTTP mode when egress to HF cannot be guaranteed."],"tags":["embeddings","model-download","huggingface","network","hf-endpoint","mirror"],"backgroundTag":"model-download-failed","analyzedSha":"aac7515d2a8c50a1f8f923c6fb77218b333560d6","analyzedAt":"2026-08-20T23:29:22.980Z","contentChangedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}