{"record":{"id":"83b1d131474412c7","repo":"abhigyanpatwari/GitNexus","slug":"circuit-open-tag-huggingface-download-circuit-83b1d1","errorCode":null,"errorMessage":"${CIRCUIT_OPEN_TAG}: HuggingFace download circuit opened after ${CB_FAILURE_THRESHOLD} consecutive failures","messagePattern":"(.+?): HuggingFace download circuit opened after (.+?) consecutive failures","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/embeddings/hf-env.ts","lineNumber":305,"sourceCode":"          }\n          circuit.recordFailure();\n          if (circuit.getState() === 'open') {\n            // Circuit just tripped — fail fast, no more retries.\n            circuitTripped = true;\n            return { retry: false };\n          }\n          // Mirror the bespoke onRetry contract: fire only when there's\n          // actually a next attempt.\n          if (attempt + 1 < maxAttempts) {\n            onRetry?.(attempt + 1, maxAttempts, error);\n          }\n          return { retry: true };\n        },\n      },\n    );\n  } catch (err) {\n    if (circuitTripped) {\n      throw new Error(\n        `${CIRCUIT_OPEN_TAG}: HuggingFace download circuit opened after ${CB_FAILURE_THRESHOLD} consecutive failures`,\n      );\n    }\n    // All retries exhausted — rethrow the last network error so\n    // isNetworkFetchError patterns in the calling code still match and\n    // surface HF_ENDPOINT guidance.\n    throw err;\n  }\n}\n","sourceCodeStart":287,"sourceCodeEnd":315,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/aac7515d2a8c50a1f8f923c6fb77218b333560d6/gitnexus/src/core/embeddings/hf-env.ts#L287-L315","documentation":"End of withHfDownloadRetry(): the retry budget (default 3 attempts, 5min per-attempt timeout, exponential backoff from 2s) is delegated to gitnexus-shared's withRetry; when a network-classified failure also trips the 3-consecutive-failure circuit mid-loop (circuitTripped sentinel), the last raw network error is replaced with this tagged CIRCUIT_OPEN message so callers can distinguish sustained outage from a single blip.","triggerScenarios":"Three consecutive network-level download failures for the embedding model within one process — each attempt timing out after 5 minutes or failing with fetch failed/ECONNREFUSED/ENOTFOUND/ETIMEDOUT/ECONNRESET — exhausting the withRetry loop and opening the breaker simultaneously.","commonSituations":"Fully blocked egress to huggingface.co (firewall/GFW), wrong HF_ENDPOINT pointing at a dead mirror, DNS failure, or an air-gapped CI runner attempting the download.","solutions":["Point at a reachable mirror: HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings.","Verify connectivity: curl -I https://huggingface.co (or your HF_ENDPOINT) from the same machine/shell.","Configure proxy env vars (HTTPS_PROXY/HTTP_PROXY) if behind a corporate proxy.","Pre-populate the model in HF_HOME/~/.cache/huggingface from a machine with access.","Avoid HF downloads entirely with HTTP embedding mode (GITNEXUS_EMBEDDING_URL + GITNEXUS_EMBEDDING_MODEL)."],"exampleFix":"# before\nnpx gitnexus analyze --embeddings  # 3 timeouts, circuit opens\n# after\nexport HF_ENDPOINT=https://hf-mirror.com\nnpx gitnexus analyze --embeddings","handlingStrategy":"fallback","validationCode":"// probe reachability before starting a long pipeline\nawait fetch(`${process.env.HF_ENDPOINT ?? 'https://huggingface.co'}`, { method: 'HEAD' });","typeGuard":"const isHfCircuitTripped = (e: unknown): boolean =>\n  e instanceof Error && e.message.includes('circuit opened after');","tryCatchPattern":"try {\n  await getEmbedder();\n} catch (e) {\n  if (isHfCircuitTripped(e)) {\n    // permanent-ish network issue: surface HF_ENDPOINT guidance, don't retry now\n  } else throw e;\n}","preventionTips":["Verify egress to huggingface.co (or your HF_ENDPOINT) before scheduling embedding jobs.","Pre-download models on networked machines and ship the HF_HOME cache.","Use HTTP embedding mode in network-restricted environments."],"tags":["embeddings","huggingface","circuit-breaker","network","download-failed"],"backgroundTag":"model-download-network-failure","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"}