What causes "Failed to download embedding model: ${errMsg}\n ${endpointHint}" in abhigyanpatwari/GitNexus?

If a custom HF_ENDPOINT is set, verify it is reachable (curl it) or unset it to fall back to huggingface.co.

Failed to download embedding model

Error message

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

What it means

initLocalEmbedder throws this when downloading the embedding model weights from Hugging Face fails. The message includes the underlying error and a network-specific hint: if HF_ENDPOINT is set, that mirror may be unreachable; otherwise it suggests huggingface.co is unreachable and shows exact HF_ENDPOINT mirror commands for unix and Windows.

Solutions

If a custom HF_ENDPOINT is set, verify it is reachable (curl it) or unset it to fall back to huggingface.co.
Set a reachable mirror and retry: HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings (Windows: set HF_ENDPOINT=https://hf-mirror.com && ...).
Fix network egress / proxy settings (e.g. GLOBAL_AGENT_HTTPS_PROXY) so the endpoint is reachable.
Pre-populate the model cache from a machine with access, or use GITNEXUS_EMBEDDING_URL HTTP embedding to avoid model download.

Example fix

// before: blocked by firewall
npx gitnexus analyze --embeddings
// after: use a mirror
export HF_ENDPOINT=https://hf-mirror.com
npx gitnexus analyze --embeddings

Defensive patterns

Strategy: retry

Validate before calling

// check endpoint reachability before init
const ep = process.env.HF_ENDPOINT ?? 'https://huggingface.co';
const ok = await fetch(ep, { method: 'HEAD' }).then(r => r.ok).catch(() => false);
if (!ok) console.warn(`Model endpoint ${ep} unreachable; set HF_ENDPOINT to a mirror`);

Try / catch

try {
  await initLocalEmbedder();
} catch (err) {
  if (String(err.message).startsWith('Failed to download embedding model')) {
    // set HF_ENDPOINT mirror and retry, or switch to HTTP embedding
  }
}

Prevention

Set HF_ENDPOINT to a reachable mirror in restricted networks before first run
Warm the model cache on a machine with internet access and reuse it
Configure proxy env vars (GLOBAL_AGENT_HTTPS_PROXY) for corporate networks
Use GITNEXUS_EMBEDDING_URL HTTP embedding when egress to HF is impossible

When it happens

Trigger: Calling initLocalEmbedder() (directly or via analyze --embeddings / embeddings sync) when the transformers.js pipeline cannot fetch model files from the configured endpoint — DNS failure, firewall, offline machine, or an unreachable HF_ENDPOINT mirror.

Common situations: Corporate networks/firewalls blocking huggingface.co; regions where HF is throttled; typos in a custom HF_ENDPOINT; CI runners without internet egress.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@ac9a4e9abd (2026-09-15). Data as JSON: /api/errors/fffe6dc24ce95f9c. Report an issue: GitHub.

Appendix: source

Thrown at gitnexus/src/core/embeddings/embedding-local-init.ts:173

          currentDevice = device;
          activeDimensions = finalConfig.dimensions;

          if (isDev) {
            logger.info(`✅ Using ${formatDeviceLabel(device)} backend`);
            logger.info('✅ Embedding model loaded successfully');
          }

          return embedderInstance!;
        } catch (deviceError) {
          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...`);
          }
          if (device === devicesToTry[devicesToTry.length - 1]) {
            throw deviceError;
          }
        }
      }

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

View on GitHub (pinned to ac9a4e9abd)