${CIRCUIT_OPEN_TAG}: HuggingFace download circuit opened aft

Error message

${CIRCUIT_OPEN_TAG}: HuggingFace download circuit opened after ${CB_FAILURE_THRESHOLD} consecutive failures

What it means

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.

Source

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

          }
          circuit.recordFailure();
          if (circuit.getState() === 'open') {
            // Circuit just tripped — fail fast, no more retries.
            circuitTripped = true;
            return { retry: false };
          }
          // Mirror the bespoke onRetry contract: fire only when there's
          // actually a next attempt.
          if (attempt + 1 < maxAttempts) {
            onRetry?.(attempt + 1, maxAttempts, error);
          }
          return { retry: true };
        },
      },
    );
  } catch (err) {
    if (circuitTripped) {
      throw new Error(
        `${CIRCUIT_OPEN_TAG}: HuggingFace download circuit opened after ${CB_FAILURE_THRESHOLD} consecutive failures`,
      );
    }
    // All retries exhausted — rethrow the last network error so
    // isNetworkFetchError patterns in the calling code still match and
    // surface HF_ENDPOINT guidance.
    throw err;
  }
}

View on GitHub (pinned to aac7515d2a)

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).

Example fix

# before
npx gitnexus analyze --embeddings  # 3 timeouts, circuit opens
# after
export HF_ENDPOINT=https://hf-mirror.com
npx gitnexus analyze --embeddings

Defensive patterns

Strategy: fallback

Validate before calling

// probe reachability before starting a long pipeline
await fetch(`${process.env.HF_ENDPOINT ?? 'https://huggingface.co'}`, { method: 'HEAD' });

Type guard

const isHfCircuitTripped = (e: unknown): boolean =>
  e instanceof Error && e.message.includes('circuit opened after');

Try / catch

try {
  await getEmbedder();
} catch (e) {
  if (isHfCircuitTripped(e)) {
    // permanent-ish network issue: surface HF_ENDPOINT guidance, don't retry now
  } else throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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