abhigyanpatwari/GitNexus · error · Error

hf-circuit-open: HuggingFace download circuit opened after 3

Error message

hf-circuit-open: HuggingFace download circuit opened after 3 consecutive failures

What it means

Thrown by withHfDownloadRetry() after the retry loop exits because the circuit breaker tripped mid-loop — i.e. the CB_FAILURE_THRESHOLD (3) consecutive network failures were recorded during this call's attempts and the breaker transitioned to 'open'. Distinct from error 113 (which fires when the breaker was already open at entry); this one fires on the call that caused the trip. The circuitTripped sentinel in the isRetryable callback marks that retries were aborted due to the breaker, not due to exhausting the attempt budget.

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

Solutions

Set HF_ENDPOINT to a reachable mirror, e.g. HF_ENDPOINT=https://hf-mirror.com.
Resolve the network issue (proxy, DNS, firewall) and retry after the 60s cooldown.
Pre-populate HF_HOME with the model from a connected host and retry offline.
Use GITNEXUS_EMBEDDING_URL to embed over HTTP and skip HuggingFace entirely.

Example fix

# before
$ npx gitnexus analyze --embeddings  # 3 net failures → circuit opens
# after
$ HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings

Defensive patterns

Strategy: fallback

Validate before calling

import { hfDownloadCircuit } from 'gitnexus/src/core/embeddings/hf-env.js';
// Inspect failure progress before a download; if near threshold, switch strategies.
const state = hfDownloadCircuit.getState();
if (state === 'open' || state === 'half-open') {
  console.warn('HF circuit tripping — set HF_ENDPOINT or use HTTP embedding mode.');
}

Type guard

import { isHfCircuitOpenError } from 'gitnexus/src/core/embeddings/hf-env.js';
const isCircuitTripMessage = (msg: string): boolean =>
  isHfCircuitOpenError(msg) && msg.includes('circuit opened after');

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)) {
    // The breaker just opened. Switch endpoint or use HTTP embeddings; do not immediately retry.
    process.env.GITNEXUS_EMBEDDING_URL = 'https://api.openai.com/v1/embeddings';
    process.env.GITNEXUS_EMBEDDING_MODEL = 'text-embedding-3-small';
    await embedText(text); // transparent HTTP path
  } else throw err;
}

Prevention

Fix the underlying network issue so the breaker can close on a successful probe.
Set HF_ENDPOINT to a mirror to avoid three consecutive failures.
Route embeddings over HTTP to avoid HuggingFace downloads.

When it happens

Trigger: A model download where each of the (up to 3) attempts fails with a network error classified by isNetworkFetchError (fetch failed, ECONNREFUSED, ENOTFOUND, ETIMEDOUT, ECONNRESET), each recorded via circuit.recordFailure(), until getState()==='open'. Non-network errors (e.g. CUDA unavailable) do not count toward the threshold and are rethrown immediately.

Common situations: huggingface.co completely unreachable (DNS/firewall/GFW); a proxy intermittently dropping connections so all three attempts fail; an offline host with no cached model.

Related errors

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