{"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":"Error","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/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/embeddings/embedder.ts#L221-L257","documentation":"Thrown inside the device-probe loop in initEmbedder() when a device attempt fails and isHfDownloadFailure(errMsg) is true — meaning the failure was a network-level fetch error (fetch failed, ECONNREFUSED, ENOTFOUND, ETIMEDOUT, ECONNRESET) or a circuit-open rejection. Network errors are not device-specific, so retrying on the next device would fail identically; the loop aborts immediately and surfaces an HF_ENDPOINT remediation hint instead of silently burning through every device.","triggerScenarios":"The model download from huggingface.co (or the configured HF_ENDPOINT mirror) fails to connect during pipeline() load. Fires once per analyze run that reaches model download; the retry/circuit logic in withHfDownloadRetry has already exhausted its budget before this rethrow.","commonSituations":"huggingface.co is blocked by the GFW or a corporate firewall; a flaky DNS causing ENOTFOUND; an unreachable/misconfigured HF_ENDPOINT mirror; an air-gapped host with no model cached under HF_HOME.","solutions":["Set HF_ENDPOINT to a reachable mirror, e.g. HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings.","Verify network reachability to the endpoint: curl -I ${HF_ENDPOINT:-https://huggingface.co}.","Pre-download the model into HF_HOME on a connected machine and copy the cache to the offline host.","Route embeddings over HTTP via GITNEXUS_EMBEDDING_URL to avoid the HuggingFace download entirely."],"exampleFix":"# before — huggingface.co unreachable\n$ npx gitnexus analyze --embeddings\n# after — use the hf-mirror.com mirror\n$ HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings","handlingStrategy":"fallback","validationCode":"import { isHfDownloadFailure } from 'gitnexus/src/core/embeddings/hf-env.js';\n// Pre-flight: confirm the HF endpoint is reachable before running analyze --embeddings.\nconst endpoint = process.env.HF_ENDPOINT?.trim() || 'https://huggingface.co';\nconst ok = await fetch(endpoint, { method: 'HEAD' }).then(() => true).catch(() => false);\nif (!ok) console.warn(`HF endpoint ${endpoint} unreachable — set HF_ENDPOINT to a mirror.`);","typeGuard":"import { isHfDownloadFailure } from 'gitnexus/src/core/embeddings/hf-env.js';\nconst isModelDownloadNetworkError = (msg: string): boolean => isHfDownloadFailure(msg);","tryCatchPattern":"try {\n  await initEmbedder();\n} catch (err) {\n  const msg = err instanceof Error ? err.message : String(err);\n  if (msg.includes('Failed to download embedding model')) {\n    // Set HF_ENDPOINT to a mirror and retry, or switch to HTTP embedding mode.\n    process.env.HF_ENDPOINT = 'https://hf-mirror.com';\n    await initEmbedder();\n  } else throw err;\n}","preventionTips":["Set HF_ENDPOINT=https://hf-mirror.com behind networks that block huggingface.co.","Pre-cache the model into HF_HOME on a connected host for offline use.","Use GITNEXUS_EMBEDDING_URL to skip the HuggingFace download path entirely."],"tags":["network","huggingface","model-download","embeddings"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}