${CIRCUIT_OPEN_TAG}: HuggingFace download circuit is open af

Error message

${CIRCUIT_OPEN_TAG}: HuggingFace download circuit is open after repeated network failures — will reset in ~${secsUntilReset}s

What it means

withHfDownloadRetry() checks the process-global HuggingFace download circuit breaker before starting any attempt. After 3 consecutive network failures (CB_FAILURE_THRESHOLD=3) the circuit opens for 60s (CB_RESET_TIMEOUT_MS); calling again during the cooldown fails fast with the seconds-until-reset instead of hammering an unreachable endpoint. This message is computed without consuming a probe permit.

Source

Thrown at gitnexus/src/core/embeddings/hf-env.ts:249

      ? Math.min(envTimeout, HF_MAX_TIMEOUT_MS)
      : HF_DOWNLOAD_TIMEOUT_MS;
  const resolvedMaxAttempts =
    Number.isFinite(envMaxAttempts) && envMaxAttempts > 0
      ? Math.min(Math.floor(envMaxAttempts), HF_MAX_ATTEMPTS_CAP)
      : HF_MAX_ATTEMPTS;
  const {
    maxAttempts = resolvedMaxAttempts,
    baseDelayMs = HF_BASE_DELAY_MS,
    timeoutMs = resolvedTimeout,
    circuit = hfDownloadCircuit,
    onRetry,
  } = options;
  if (circuit.getState() === 'open') {
    // Compute remaining cooldown without consuming a probe permit.
    const openedAt = circuit.getOpenedAt();
    const secsUntilReset =
      openedAt !== null ? Math.ceil((circuit.getCooldownMs() - (Date.now() - openedAt)) / 1000) : 0;
    throw new Error(
      `${CIRCUIT_OPEN_TAG}: HuggingFace download circuit is open after repeated network failures` +
        (secsUntilReset > 0 ? ` — will reset in ~${secsUntilReset}s` : ''),
    );
  }

  // Retry budget delegated to `withRetry` from gitnexus-shared. The
  // HF-specific bits — per-attempt timeout, network-vs-non-network
  // classification, circuit-breaker recording, onRetry callback — wire
  // through the `isRetryable` callback. `circuitTripped` is the
  // sentinel that lets us replace the final thrown error with a
  // CIRCUIT_OPEN_TAG message when the breaker tripped mid-loop.
  let circuitTripped = false;

  try {
    return await withRetry(
      async () => {
        const result = await withDownloadTimeout(fn, timeoutMs);
        circuit.recordSuccess();

View on GitHub (pinned to aac7515d2a)

Solutions

Wait for the stated cooldown (~60s) before retrying.
Set HF_ENDPOINT to a reachable mirror, e.g. HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings.
Fix the underlying network issue (proxy env vars HTTP(S)_PROXY, DNS, firewall) before retrying.
Pre-cache the model once on a machine with access (HF_HOME cache dir) and reuse it.
Switch to HTTP embedding mode (GITNEXUS_EMBEDDING_URL + GITNEXUS_EMBEDDING_MODEL) so no HF download is needed.

Example fix

# before
npx gitnexus analyze --embeddings   # fails, retry instantly -> circuit open
npx gitnexus analyze --embeddings
# after
HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings

Defensive patterns

Strategy: retry

Validate before calling

// circuit state is internal; the practical pre-check is connectivity
import { isNetworkFetchError } from './hf-env'; // classify after first failure

Type guard

const isCircuitOpen = (e: unknown): boolean =>
  e instanceof Error && e.message.includes('circuit is open');

Try / catch

try {
  await getEmbedder();
} catch (e) {
  if (isCircuitOpen(e)) {
    const secs = Number(/~(\d+)s/.exec(e.message)?.[1] ?? 60);
    await sleep((secs + 1) * 1000);
    return getEmbedder(); // single bounded retry after cooldown
  }
  throw e;
}

Prevention

Set HF_ENDPOINT to a proven-reachable mirror before the first download.
Cache the downloaded model (HF_HOME on shared/persistent storage) so the breaker never matters on later runs.
Do not tight-loop retries around embedding initialization; space them beyond the 60s cooldown.

When it happens

Trigger: A model download already failed 3 times in this process (fetch failed / ECONNREFUSED / ENOTFOUND / ETIMEDOUT / ECONNRESET) and a new download attempt starts within the ~60s cooldown window — e.g. a retry loop around `analyze --embeddings` or an MCP server re-initializing the embedder.

Common situations: huggingface.co unreachable from corporate proxies, the GFW, or air-gapped networks; users or scripts that immediately rerun the failed command instead of waiting; flaky Wi-Fi where 3 attempts burn through quickly.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@aac7515d2a (2026-08-20). Data as JSON: /api/errors/b7eb1f933e76869b. Report an issue: GitHub.