abhigyanpatwari/GitNexus · error · Error

Failed to load embedding model

Error message

Failed to load embedding model

What it means

In initEmbedder's device loop, when the last-resort 'cpu' device fails to load the model for a reason that is not an HF download failure, this generic message is thrown. The model bytes were obtained (or cached) but the pipeline could not be constructed on CPU — pointing at corrupted cache files or a transformers.js/onnxruntime version mismatch rather than networking.

Source

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

          }
          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. Clear the model cache and retry so it re-downloads cleanly: remove the transformers.js cache dir (HF_HOME / default ~/.cache/huggingface or .cache/transformers.js).
2. Refresh the embedding stack with `gitnexus embeddings install` to realign @huggingface/transformers and onnxruntime-node versions.
3. Update GitNexus to the latest patch so stack pins match the loader code.
4. If local loading stays broken, fall back to HTTP embeddings via GITNEXUS_EMBEDDING_URL/GITNEXUS_EMBEDDING_MODEL.

Example fix

# before: corrupt/stale cache prevents cpu load
$ gitnexus analyze --embeddings
# → Failed to load embedding model

# after: purge cache and refresh the stack, then retry
$ rm -rf ~/.cache/huggingface/transformers
$ gitnexus embeddings install
$ gitnexus analyze --embeddings

// Cheap sanity check on the cached model before starting a long analyze
import { existsSync } from 'node:fs';
import { join } from 'node:path';

const cacheDir = process.env.HF_HOME
  ? join(process.env.HF_HOME, 'transformers')
  : join(process.env.HOME ?? '', '.cache', 'huggingface', 'transformers');
const modelCacheOk = existsSync(cacheDir); // absence just means a fresh download, corruption still surfaces at load

try {
  await runAnalyze({ embeddings: true });
} catch (err) {
  const msg = err instanceof Error ? err.message : '';
  if (msg === 'Failed to load embedding model') {
    // not a network issue: clear cache once, then fall back to HTTP embeddings if it recurs
    await rm(hfTransformersCache(), { recursive: true, force: true });
    return runAnalyzeWithHttpEmbeddings();
  }
  throw err;
}

When it happens

Trigger: Loading a cached model on cpu after an interrupted first download left corrupt files in the transformers.js cache dir; upgrading gitnexus (which pins new @huggingface/transformers / onnxruntime-node versions) while an old cache layout remains; native runtime load failing for non-network reasons (missing system libs, OOM).

Common situations: Rerunning --embeddings after a Ctrl-C during the first download; long-lived machines with stale HF/transformers caches; Node major-version upgrades breaking native module ABI alongside the embedding stack.

Related errors

• Local semantic embeddings are unavailable on macOS Intel (da
• Local semantic embeddings are unavailable: the optional embe
• No suitable device found for embedding model
• Local semantic embeddings are unavailable on macOS Intel (da
• Local semantic embeddings are unavailable: the optional embe

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