abhigyanpatwari/GitNexus · error · Error

hf-circuit-open: HuggingFace download circuit is open after

Error message

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

What it means

Thrown by withHfDownloadRetry() at entry when the module-level HuggingFace download circuit breaker (hfDownloadCircuit) is already in the 'open' state. The breaker opens after CB_FAILURE_THRESHOLD (3) consecutive network failures and stays open for CB_RESET_TIMEOUT_MS (60s); while open, every call fails immediately without consuming a probe permit, computing the remaining cooldown from getOpenedAt() so the user knows how long to wait. This prevents stampeding huggingface.co during an outage.

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

Solutions

Wait until the stated cooldown (~60s) elapses, then retry.
Set HF_ENDPOINT to a reachable mirror (e.g. https://hf-mirror.com) and retry.
Fix the underlying network issue (proxy, DNS, firewall) so the breaker can close on a successful probe.
Route embeddings over HTTP via GITNEXUS_EMBEDDING_URL to avoid HuggingFace downloads entirely.

Example fix

# before — breaker open, immediate retry fails again
$ npx gitnexus analyze --embeddings  # fails
$ npx gitnexus analyze --embeddings  # hf-circuit-open
# after — wait for cooldown, use a mirror
$ HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings

Defensive patterns

Strategy: retry

Validate before calling

import { hfDownloadCircuit } from 'gitnexus/src/core/embeddings/hf-env.js';
// Check the breaker state before attempting a download.
if (hfDownloadCircuit.getState() === 'open') {
  console.warn('HF download circuit open — wait for cooldown or set HF_ENDPOINT to a mirror.');
}

Type guard

import { isHfCircuitOpenError } from 'gitnexus/src/core/embeddings/hf-env.js';
const isCircuitOpen = (msg: string): boolean => isHfCircuitOpenError(msg);

Try / catch

import { isHfCircuitOpenError } from 'gitnexus/src/core/embeddings/hf-env.js';
try {
  await initEmbedder();
} catch (err) {
  const msg = err instanceof Error ? err.message : String(err);
  if (isHfCircuitOpenError(msg)) {
    // Wait for the stated cooldown, or switch to a mirror / HTTP embedding mode.
    console.warn(msg);
    process.env.HF_ENDPOINT = 'https://hf-mirror.com';
    await initEmbedder();
  } else throw err;
}

Prevention

Set HF_ENDPOINT to a reachable mirror to keep the breaker closed.
Do not retry-in-a-tight-loop after a circuit open — respect the ~60s cooldown.
Use GITNEXUS_EMBEDDING_URL to bypass the HF download path entirely.

When it happens

Trigger: A second or subsequent model-download attempt within 60s of three consecutive network failures in the same process. The first trip throws error 114 (the trip itself); subsequent calls during the cooldown throw this 113 variant with the reset countdown.

Common situations: Retrying `analyze --embeddings` immediately after a network failure; a long-running MCP server that keeps attempting downloads while HF is unreachable; multiple parallel analyze processes in one process tripping the breaker then retrying.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@d540b00184 (2026-08-12). Data as JSON: /api/errors/966eebbf79e63930. Report an issue: GitHub.