abhigyanpatwari/GitNexus · error · Error

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

Error message

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

What it means

Thrown inside the device-probe loop in initEmbedder() when a device attempt fails and isHfDownloadFailure(errMsg) is true — meaning the failure was a network-level fetch error (fetch failed, ECONNREFUSED, ENOTFOUND, ETIMEDOUT, ECONNRESET) or a circuit-open rejection. Network errors are not device-specific, so retrying on the next device would fail identically; the loop aborts immediately and surfaces an HF_ENDPOINT remediation hint instead of silently burning through every device.

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

Solutions

  1. Set HF_ENDPOINT to a reachable mirror, e.g. HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings.
  2. Verify network reachability to the endpoint: curl -I ${HF_ENDPOINT:-https://huggingface.co}.
  3. Pre-download the model into HF_HOME on a connected machine and copy the cache to the offline host.
  4. Route embeddings over HTTP via GITNEXUS_EMBEDDING_URL to avoid the HuggingFace download entirely.

Example fix

# before — huggingface.co unreachable
$ npx gitnexus analyze --embeddings
# after — use the hf-mirror.com mirror
$ HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings
Defensive patterns

Strategy: fallback

Validate before calling

import { isHfDownloadFailure } from 'gitnexus/src/core/embeddings/hf-env.js';
// Pre-flight: confirm the HF endpoint is reachable before running analyze --embeddings.
const endpoint = process.env.HF_ENDPOINT?.trim() || 'https://huggingface.co';
const ok = await fetch(endpoint, { method: 'HEAD' }).then(() => true).catch(() => false);
if (!ok) console.warn(`HF endpoint ${endpoint} unreachable — set HF_ENDPOINT to a mirror.`);

Type guard

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

Try / catch

try {
  await initEmbedder();
} catch (err) {
  const msg = err instanceof Error ? err.message : String(err);
  if (msg.includes('Failed to download embedding model')) {
    // Set HF_ENDPOINT to a mirror and retry, or switch to HTTP embedding mode.
    process.env.HF_ENDPOINT = 'https://hf-mirror.com';
    await initEmbedder();
  } else throw err;
}

Prevention

When it happens

Trigger: The model download from huggingface.co (or the configured HF_ENDPOINT mirror) fails to connect during pipeline() load. Fires once per analyze run that reaches model download; the retry/circuit logic in withHfDownloadRetry has already exhausted its budget before this rethrow.

Common situations: huggingface.co is blocked by the GFW or a corporate firewall; a flaky DNS causing ENOTFOUND; an unreachable/misconfigured HF_ENDPOINT mirror; an air-gapped host with no model cached under HF_HOME.

Related errors

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