abhigyanpatwari/GitNexus · error · Error

GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${p

Error message

GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${process.env.GITNEXUS_EMBEDDING_DIMS}"

What it means

Thrown at module load time (schema.ts import) when the GITNEXUS_EMBEDDING_DIMS environment variable is set but parses to NaN or a non-positive integer. The default is 384 (matching snowflake-arctic-embed-xs embeddings); the env var allows overriding for alternative embedding models with different vector dimensions. This is a fail-fast guard: an invalid dimension would create a CodeEmbedding table with the wrong array size, causing silent vector-search failures or data corruption. The check runs parseInt with radix 10 and validates via Number.isNaN and > 0.

Source

Thrown at gitnexus/src/core/lbug/schema.ts:599

export const RELATION_SCHEMA = `
CREATE REL TABLE ${REL_TABLE_NAME} (
${STRUCTURAL_PAIR_DDL},
${generatedPairDdl()},
  type STRING,
  confidence DOUBLE,
  reason STRING,
  step INT32
)`;

// ============================================================================
// EMBEDDING TABLE SCHEMA
// Separate table for vector storage to avoid copy-on-write overhead
// ============================================================================

/** Embedding vector dimensions. Default 384 (snowflake-arctic-embed-xs). */
const _rawDims = parseInt(process.env.GITNEXUS_EMBEDDING_DIMS ?? '384', 10);
if (Number.isNaN(_rawDims) || _rawDims <= 0) {
  throw new Error(
    `GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${process.env.GITNEXUS_EMBEDDING_DIMS}"`,
  );
}
export const EMBEDDING_DIMS = _rawDims;

/** HNSW vector index name for the CodeEmbedding table. */
export const EMBEDDING_INDEX_NAME = 'code_embedding_idx';

/**
 * Sentinel value for "no content hash available" — used in legacy DBs and null rows.
 * Nodes with this hash are always treated as stale and re-embedded.
 */
export const STALE_HASH_SENTINEL = '';

export const EMBEDDING_SCHEMA = `
CREATE NODE TABLE ${EMBEDDING_TABLE_NAME} (
  id STRING,
  nodeId STRING,

View on GitHub (pinned to d540b00184)

Solutions

Set GITNEXUS_EMBEDDING_DIMS to a positive integer (e.g. 384 for snowflake-arctic-embed-xs, 768 for larger models), or unset it to use the default 384
Verify there are no trailing spaces, newlines, or quotes in the environment variable value
If using Docker, check the ENV/args syntax: `GITNEXUS_EMBEDDING_DIMS=384` (no quotes in shell)
Restart the GitNexus process after correcting the env var

Example fix

# before — non-integer value
export GITNEXUS_EMBEDDING_DIMS=384px
# after — positive integer
export GITNEXUS_EMBEDDING_DIMS=384

Defensive patterns

Strategy: validation

Validate before calling

// Validate GITNEXUS_EMBEDDING_DIMS before importing schema.ts
const rawDims = process.env.GITNEXUS_EMBEDDING_DIMS;
if (rawDims !== undefined) {
  const parsed = parseInt(rawDims, 10);
  if (Number.isNaN(parsed) || parsed <= 0) {
    throw new Error(`Invalid GITNEXUS_EMBEDDING_DIMS="${rawDims}" — must be a positive integer`);
  }
}

Type guard

function isValidEmbeddingDims(value: string | undefined): value is string {
  if (value === undefined) return true; // default is fine
  const n = parseInt(value, 10);
  return !Number.isNaN(n) && n > 0 && String(n) === value.trim();
}

Try / catch

// This is a module-load-time error — wrap the import in a try-catch
// in the entry point to give a friendlier message
try {
  await import('./schema');
} catch (e) {
  if (e instanceof Error && e.message.includes('GITNEXUS_EMBEDDING_DIMS')) {
    console.error('Configuration error:', e.message);
    console.error('Set GITNEXUS_EMBEDDING_DIMS to a positive integer (e.g. 384) or unset it.');
    process.exit(1);
  }
  throw e;
}

Prevention

Validate environment variables in a startup config module before importing schema-heavy modules
Use a .env validator (e.g. envalid, zod) that catches type errors at startup
In Docker, ensure ENV values have no quotes or trailing whitespace
Document valid values for GITNEXUS_EMBEDDING_DIMS (384, 768, etc.) in the configuration docs

When it happens

Trigger: Setting GITNEXUS_EMBEDDING_DIMS to a non-numeric value (e.g. 'auto', '384px'), a float (e.g. '384.5'), zero, a negative number, or an empty string. The error fires immediately when schema.ts is imported, which happens early in any GitNexus process startup (CLI, serve, MCP). The raw env var value is included in the error for diagnosis.

Common situations: A developer sets GITNEXUS_EMBEDDING_DIMS to match a new embedding model but typos the value; a CI pipeline sets it from a template variable that resolves to empty; a Docker Compose environment variable with a trailing newline or quotes that breaks parseInt; confusion between embedding dimensions and model dimensions.

Related errors

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