abhigyanpatwari/GitNexus · error

Failed to download embedding model

Error message

Failed to download embedding model: ${errMsg}
  ${endpointHint}

What it means

While initializing the local embedding pipeline, model download failures are detected via isHfDownloadFailure() on the error message and rethrown with endpoint guidance instead of falling through the device-fallback list — network errors fail identically on every device, so trying the next one would only burn time. If HF_ENDPOINT is set, the hint names it as possibly unreachable; otherwise the hint suggests a mirror (e.g. hf-mirror.com) for networks that cannot reach huggingface.co.

Solutions

  1. If HF_ENDPOINT is already set, verify it is reachable: curl -fsS "$HF_ENDPOINT" — a typo'd mirror URL produces this same error.
  2. Otherwise switch to a mirror: HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings.
  3. Or pre-warm/cache the model on a machine with access and ship the cache (HF_HOME) to the restricted machine.
  4. Longer term, use HTTP embeddings (GITNEXUS_EMBEDDING_URL) so no HF download is needed at all.

Example fix

# before
npx gitnexus analyze --embeddings
# Failed to download embedding model: fetch failed
#   huggingface.co may be unreachable from your network...

# after
HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings
# Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings
Defensive patterns

Strategy: retry

Validate before calling

// Probe endpoint reachability before first embeddings run:
async function hfEndpointReachable(timeoutMs = 10_000): Promise<boolean> {
  const endpoint = process.env.HF_ENDPOINT ?? 'https://huggingface.co';
  try {
    const res = await fetch(endpoint, { method: 'HEAD', signal: AbortSignal.timeout(timeoutMs) });
    return res.ok || res.status === 405; // HEAD often 405s on mirrors but proves reachability
  } catch {
    return false;
  }
}

Try / catch

try {
  await analyze({ repo: '.', embeddings: true });
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Failed to download embedding model:')) {
    if (!process.env.HF_ENDPOINT) {
      process.env.HF_ENDPOINT = 'https://hf-mirror.com';
      return analyze({ repo: '.', embeddings: true }); // retry once via mirror
    }
    throw new Error('Configured HF_ENDPOINT is unreachable — fix or unset it');
  }
  throw err;
}

Prevention

When it happens

Trigger: First local-embeddings run on a machine where transformers.js must download the model from the HF hub and the fetch fails (offline, DNS, firewall, 403/429, regional blocking). The device loop in getOrCreateEmbedder() catches the per-device error, classifies the message as an HF download failure, and throws with the hint.

Common situations: Corporate networks blocking huggingface.co, mainland-China networks needing a mirror, CI runners with no outbound internet, an unreachable/misconfigured private HF_ENDPOINT, or a transient HF outage during first run.

Related errors

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

Appendix: source

Thrown at gitnexus/src/core/embeddings/embedder.ts:239

            logger.info(`✅ Using ${label} backend`);
            logger.info('✅ Embedding model loaded successfully');
          }

          return embedderInstance!;
        } catch (deviceError) {
          // Network errors and circuit-open errors are not device-specific —
          // they will fail the same way on every device. Rethrow immediately
          // with actionable HF_ENDPOINT guidance rather than silently falling
          // back to the next device.
          const errMsg = deviceError instanceof Error ? deviceError.message : String(deviceError);
          if (isHfDownloadFailure(errMsg)) {
            const endpointHint = process.env.HF_ENDPOINT
              ? `The configured endpoint (${process.env.HF_ENDPOINT}) may be unreachable.`
              : `huggingface.co may be unreachable from your network.\n` +
                `  Set HF_ENDPOINT to a mirror and retry:\n` +
                `    HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings\n` +
                `    (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings)`;
            throw new Error(`Failed to download embedding model: ${errMsg}\n  ${endpointHint}`);
          }
          if (isDev && (device === 'cuda' || device === 'dml')) {
            const gpuType = device === 'dml' ? 'DirectML' : 'CUDA';
            logger.info(`⚠️  ${gpuType} not available, falling back to CPU...`);
          }
          // Continue to next device in list
          if (device === devicesToTry[devicesToTry.length - 1]) {
            throw deviceError; // Last device failed, propagate error
          }
        }
      }

      throw new Error('No suitable device found for embedding model');
    } catch (error) {
      isInitializing = false;
      initPromise = null;
      embedderInstance = null;
      throw error;

View on GitHub (pinned to aac7515d2a)