abhigyanpatwari/GitNexus · error · Error

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

Error message

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

What it means

While initEmbedder probes devices, a device failure whose message matches isHfDownloadFailure is treated as device-independent network trouble and rethrown immediately with the underlying error plus an HF_ENDPOINT hint, rather than silently trying the next device. It means the embedding model could not be fetched from huggingface.co (or the configured HF_ENDPOINT mirror).

Source

Thrown at gitnexus/src/mcp/core/embedder.ts:154

            restoreStdout();
            process.stderr.write = realStderrWrite;
          }
          logger.info({ device }, 'GitNexus: Embedding model loaded');
          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 (device === 'cpu') throw new Error('Failed to load embedding model');
        }
      }

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

  return initPromise;
};

View on GitHub (pinned to aac7515d2a)

Solutions

  1. Set HF_ENDPOINT to a mirror and retry: `HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings` (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings).
  2. Fix egress: allow huggingface.co (and cdn) through the proxy/firewall, or set HTTPS_PROXY correctly for the Node process.
  3. Pre-download the model once on a machine with access and share the cache via HF_HOME.
  4. Switch to HTTP embeddings: set GITNEXUS_EMBEDDING_URL + GITNEXUS_EMBEDDING_MODEL at an OpenAI-compatible endpoint so no HF download is needed.

Example fix

# before: direct huggingface.co blocked
$ gitnexus analyze --embeddings
# → Failed to download embedding model: ...

# after: use the HF mirror endpoint
$ HF_ENDPOINT=https://hf-mirror.com gitnexus analyze --embeddings
Defensive patterns

Strategy: retry

Validate before calling

// Check endpoint reachability before the first embeddings run
async function hfEndpointReachable(): Promise<boolean> {
  const base = process.env.HF_ENDPOINT ?? 'https://huggingface.co';
  try {
    const res = await fetch(`${base}/transformers.js/all-MiniLM-L6-v2/resolve/latest/config.json`, {
      method: 'HEAD',
      signal: AbortSignal.timeout(5000),
    });
    return res.ok;
  } catch {
    return false;
  }
}

Try / catch

let lastErr: unknown;
for (let attempt = 0; attempt < 3; attempt++) {
  try {
    return await runAnalyze({ embeddings: true });
  } catch (err) {
    const msg = err instanceof Error ? err.message : String(err);
    if (!msg.includes('Failed to download embedding model')) throw err;
    lastErr = err;
    await sleep(2 ** attempt * 1000); // network issues are often transient; mirror env persists
  }
}
throw lastErr;

Prevention

When it happens

Trigger: First run of `analyze --embeddings` or MCP semantic search with no model cached, on a network where huggingface.co (or a configured HF_ENDPOINT) is unreachable: GFW-style blocking, corporate firewalls, TLS interception, proxy misconfiguration, or an HF outage. Also fires when a custom HF_ENDPOINT is itself down.

Common situations: Developers in regions requiring HF mirrors; CI runners without egress to huggingface.co; a wrong/expired HF_ENDPOINT pointing at a dead internal mirror; laptops on guest networks.

Related errors

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