What causes "GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${rawDims}"" in abhigyanpatwari/GitNexus?

Set GITNEXUS_EMBEDDING_DIMS to the model's plain integer dimension (e.g. 384, 768, 1536).

abhigyanpatwari/GitNexus · error · Error

GITNEXUS_EMBEDDING_DIMS must be a positive integer, got

Error message

GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${rawDims}"

What it means

readConfig() validates GITNEXUS_EMBEDDING_DIMS (the declared vector dimension of the endpoint's model) when HTTP embedding mode is active. A value that is not pure digits throws with the EMBEDDING_DIMS_ENV_ERROR_LEAD ('GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "..."'). Deliberately thrown only where config is consumed (httpEmbed/httpEmbedQuery/getHttpDimensions), never by the isHttpMode presence probe (#2385).

Solutions

Set GITNEXUS_EMBEDDING_DIMS to the model's plain integer dimension (e.g. 384, 768, 1536).
Unset it if your endpoint returns full-dimension vectors — it is optional.
Run `gitnexus doctor`-style config checks after editing embedding env vars.

Example fix

# before
export GITNEXUS_EMBEDDING_DIMS='768d'
# after
export GITNEXUS_EMBEDDING_DIMS=768

Defensive patterns

Strategy: validation

Validate before calling

const dims = process.env.GITNEXUS_EMBEDDING_DIMS;
if (dims !== undefined && dims !== '' && !/^\d+$/.test(dims)) {
  throw new Error(`Bad GITNEXUS_EMBEDDING_DIMS: "${dims}"`);
}

Type guard

const isDimsEnvError = (e: unknown): boolean =>
  e instanceof Error && e.message.includes('GITNEXUS_EMBEDDING_DIMS must be');

Try / catch

try {
  await httpEmbed(texts);
} catch (e) {
  if (isDimsEnvError(e)) { /* fix/unset GITNEXUS_EMBEDDING_DIMS; non-retryable */ }
  else throw e;
}

Prevention

Keep isHttpMode() for mode probing; only readConfig()-style paths validate DIMS — expect the throw at first embed call, not at startup.
Use plain integers for dimensions and know your model's dim (384/768/1024/1536...).
Add a startup config lint for all GITNEXUS_EMBEDDING_* vars in deployment scripts.

When it happens

Trigger: Setting GITNEXUS_EMBEDDING_URL + GITNEXUS_EMBEDDING_MODEL plus GITNEXUS_EMBEDDING_DIMS='768.0', '768d', 'true', or '-1' and running analyze --embeddings or any semantic query in HTTP mode.

Common situations: Copying 'nq8d' style model names into DIMS, quotes/whitespace from .env, or setting dims when the endpoint ignores/derives them itself.

Related errors

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

Appendix: source

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

/**
 * Build config from the current process.env snapshot.
 * Returns null when GITNEXUS_EMBEDDING_URL + GITNEXUS_EMBEDDING_MODEL are unset.
 * Not cached — env vars are read fresh so late configuration takes effect.
 * Validates GITNEXUS_EMBEDDING_DIMS and throws on a malformed value; callers
 * that only need to know whether HTTP mode is *configured* must use
 * {@link isHttpMode} (a presence probe that never throws), not this.
 */
const readConfig = (): HttpConfig | null => {
  const baseUrl = process.env.GITNEXUS_EMBEDDING_URL;
  const model = process.env.GITNEXUS_EMBEDDING_MODEL;
  if (!baseUrl || !model) return null;

  const rawDims = process.env.GITNEXUS_EMBEDDING_DIMS;
  let dimensions: number | undefined;
  if (rawDims !== undefined) {
    if (!/^\d+$/.test(rawDims)) {
      throw new Error(`${EMBEDDING_DIMS_ENV_ERROR_LEAD}, got "${rawDims}"`);
    }
    const parsed = parseInt(rawDims, 10);
    if (parsed <= 0) {
      throw new Error(`${EMBEDDING_DIMS_ENV_ERROR_LEAD}, got "${rawDims}"`);
    }
    dimensions = parsed;
  }

  const rawRequestDims = process.env.GITNEXUS_EMBEDDING_REQUEST_DIMS?.trim();
  let requestDimensions = dimensions;
  if (rawRequestDims) {
    if (/^(omit|none|off|false|0)$/i.test(rawRequestDims)) {
      requestDimensions = undefined;
    } else {
      if (!/^\d+$/.test(rawRequestDims)) {
        throw new Error(`${EMBEDDING_REQUEST_DIMS_ENV_ERROR_LEAD}, got "${rawRequestDims}"`);
      }
      const parsed = parseInt(rawRequestDims, 10);

View on GitHub (pinned to ac9a4e9abd)