{"record":{"id":"ec1bb900871821d9","repo":"abhigyanpatwari/GitNexus","slug":"failed-to-download-embedding-model-errmsg","errorCode":null,"errorMessage":"Failed to download embedding model: ${errMsg}\n  ${endpointHint}","messagePattern":"Failed to download embedding model: (.+?)\n  (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/embeddings/embedder.ts","lineNumber":239,"sourceCode":"            logger.info(`✅ Using ${label} backend`);\n            logger.info('✅ Embedding model loaded successfully');\n          }\n\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 (isDev && (device === 'cuda' || device === 'dml')) {\n            const gpuType = device === 'dml' ? 'DirectML' : 'CUDA';\n            logger.info(`⚠️  ${gpuType} not available, falling back to CPU...`);\n          }\n          // Continue to next device in list\n          if (device === devicesToTry[devicesToTry.length - 1]) {\n            throw deviceError; // Last device failed, propagate error\n          }\n        }\n      }\n\n      throw new Error('No suitable device found for embedding model');\n    } catch (error) {\n      isInitializing = false;\n      initPromise = null;\n      embedderInstance = null;\n      throw error;","sourceCodeStart":221,"sourceCodeEnd":257,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/aac7515d2a8c50a1f8f923c6fb77218b333560d6/gitnexus/src/core/embeddings/embedder.ts#L221-L257","documentation":"While initializing the local embedding pipeline, model download failures are detected via isHfDownloadFailure() on the error message and rethrown with endpoint guidance instead of falling through the device-fallback list — network errors fail identically on every device, so trying the next one would only burn time. If HF_ENDPOINT is set, the hint names it as possibly unreachable; otherwise the hint suggests a mirror (e.g. hf-mirror.com) for networks that cannot reach huggingface.co.","triggerScenarios":"First local-embeddings run on a machine where transformers.js must download the model from the HF hub and the fetch fails (offline, DNS, firewall, 403/429, regional blocking). The device loop in getOrCreateEmbedder() catches the per-device error, classifies the message as an HF download failure, and throws with the hint.","commonSituations":"Corporate networks blocking huggingface.co, mainland-China networks needing a mirror, CI runners with no outbound internet, an unreachable/misconfigured private HF_ENDPOINT, or a transient HF outage during first run.","solutions":["If HF_ENDPOINT is already set, verify it is reachable: curl -fsS \"$HF_ENDPOINT\" — a typo'd mirror URL produces this same error.","Otherwise switch to a mirror: HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings.","Or pre-warm/cache the model on a machine with access and ship the cache (HF_HOME) to the restricted machine.","Longer term, use HTTP embeddings (GITNEXUS_EMBEDDING_URL) so no HF download is needed at all."],"exampleFix":"# before\nnpx gitnexus analyze --embeddings\n# Failed to download embedding model: fetch failed\n#   huggingface.co may be unreachable from your network...\n\n# after\nHF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings\n# Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings","handlingStrategy":"retry","validationCode":"// Probe endpoint reachability before first embeddings run:\nasync function hfEndpointReachable(timeoutMs = 10_000): Promise<boolean> {\n  const endpoint = process.env.HF_ENDPOINT ?? 'https://huggingface.co';\n  try {\n    const res = await fetch(endpoint, { method: 'HEAD', signal: AbortSignal.timeout(timeoutMs) });\n    return res.ok || res.status === 405; // HEAD often 405s on mirrors but proves reachability\n  } catch {\n    return false;\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await analyze({ repo: '.', embeddings: true });\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Failed to download embedding model:')) {\n    if (!process.env.HF_ENDPOINT) {\n      process.env.HF_ENDPOINT = 'https://hf-mirror.com';\n      return analyze({ repo: '.', embeddings: true }); // retry once via mirror\n    }\n    throw new Error('Configured HF_ENDPOINT is unreachable — fix or unset it');\n  }\n  throw err;\n}","preventionTips":["Set HF_ENDPOINT to a reachable mirror in restricted networks before the first --embeddings run.","Pre-warm the model cache (HF_HOME) on a connected machine and ship it to locked-down hosts.","Verify custom HF_ENDPOINT values with curl before relying on them.","Consider GITNEXUS_EMBEDDING_URL HTTP embeddings to remove the HF download dependency entirely."],"tags":["embeddings","network","model-download","huggingface","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-23T08:17:48.524Z"}