abhigyanpatwari/GitNexus · error · Error

HTTP embedding not configured

Error message

HTTP embedding not configured

What it means

Plain Error thrown by httpEmbed() when readConfig() returns null, which happens whenever either GITNEXUS_EMBEDDING_URL or GITNEXUS_EMBEDDING_MODEL is unset. Both env vars are required to activate HTTP embedding mode; the API key defaults to 'unused' so it is never the trigger. Config is re-read from env on every call, so the check reflects the environment at call time.

Solutions

  1. Set both required vars: export GITNEXUS_EMBEDDING_URL=http://localhost:11434/v1 and export GITNEXUS_EMBEDDING_MODEL=<model-id>.
  2. Verify with the library's own probe: node -e "console.log(require('./dist/core/embeddings/http-client.js').isHttpMode())" should print true.
  3. Check spelling of both env var names and that the shell/CI actually exports them into the process running gitnexus.
  4. If you intended local embeddings, unset both vars so the ONNX embedder path is used instead of httpEmbed.

Example fix

# before
export GITNEXUS_EMBEDDING_URL=http://localhost:11434/v1
gitnexus analyze  # -> Error: HTTP embedding not configured (model missing)

# after
export GITNEXUS_EMBEDDING_URL=http://localhost:11434/v1
export GITNEXUS_EMBEDDING_MODEL=nomic-embed-text
gitnexus analyze
Defensive patterns

Strategy: validation

Validate before calling

import { isHttpMode } from './core/embeddings/http-client.js';

// Call before httpEmbed(): both vars are required for HTTP embedding mode.
export function assertHttpEmbeddingConfigured(): void {
  if (!isHttpMode()) {
    const missing = [
      !process.env.GITNEXUS_EMBEDDING_URL && 'GITNEXUS_EMBEDDING_URL',
      !process.env.GITNEXUS_EMBEDDING_MODEL && 'GITNEXUS_EMBEDDING_MODEL',
    ].filter(Boolean);
    throw new Error(`HTTP embedding requires both env vars; missing: ${missing.join(', ')}`);
  }
}

Type guard

// Pure presence probe — mirrors the library's own isHttpMode() logic.
export const isHttpEmbeddingConfigured = (): boolean =>
  Boolean(process.env.GITNEXUS_EMBEDDING_URL && process.env.GITNEXUS_EMBEDDING_MODEL);

Try / catch

try {
  vectors = await httpEmbed(texts);
} catch (err) {
  if (err instanceof Error && err.message === 'HTTP embedding not configured') {
    // Config problem, not data: point at the env vars or switch embedder.
    throw new Error('Set GITNEXUS_EMBEDDING_URL and GITNEXUS_EMBEDDING_MODEL (or unset both to use the local embedder)', { cause: err });
  }
  throw err;
}

Prevention

When it happens

Trigger: Invoking httpEmbed(texts) with a non-empty array while GITNEXUS_EMBEDDING_URL or GITNEXUS_EMBEDDING_MODEL is missing from process.env — e.g. the .env file was not loaded, the var was exported in a different shell, or CI masked one of the two names.

Common situations: Setting only GITNEXUS_EMBEDDING_URL because the local server ignores the model field; typos in the env var name (GITNEXUS_EMBEDDINGS_URL); dotenv file not loaded before the embedding call; CI secrets naming the vars differently than the documented pair.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at gitnexus/src/core/embeddings/http-client.ts:620

  }
  return parsed;
};

/**
 * Embed texts via the HTTP backend, splitting into batches.
 * Reads config from env vars on every call.
 *
 * @param texts - Array of texts to embed
 * @returns Array of Float32Array embedding vectors
 */
export const httpEmbed = async (
  texts: string[],
  requestOptions: EmbeddingRequestOptions = {},
): Promise<Float32Array[]> => {
  if (texts.length === 0) return [];

  const config = readConfig();
  if (!config) throw new Error('HTTP embedding not configured');

  const url = `${config.baseUrl}/embeddings`;
  const allVectors: Float32Array[] = [];

  for (const [batchIndex, batch] of chunk(texts, HTTP_BATCH_SIZE).entries()) {
    const items = await httpEmbedBatch(
      url,
      batch,
      config.model,
      config.apiKey,
      batchIndex,
      config.requestDimensions,
      requestOptions,
      config.maxAttempts,
      config.retryCapMs,
      config.minIntervalMs,
      config.timeoutMs,
      config.retryTimeouts,

View on GitHub (pinned to ac9a4e9abd)