{"record":{"id":"cb19295bc6c2188f","repo":"abhigyanpatwari/GitNexus","slug":"gitnexus-embedding-dims-must-be-a-positive-integer-cb1929","errorCode":null,"errorMessage":"GITNEXUS_EMBEDDING_DIMS must be a positive integer, got \"${process.env.GITNEXUS_EMBEDDING_DIMS}\"","messagePattern":"GITNEXUS_EMBEDDING_DIMS must be a positive integer, got \"(.+?)\"","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/lbug/schema.ts","lineNumber":599,"sourceCode":"export const RELATION_SCHEMA = `\nCREATE REL TABLE ${REL_TABLE_NAME} (\n${STRUCTURAL_PAIR_DDL},\n${generatedPairDdl()},\n  type STRING,\n  confidence DOUBLE,\n  reason STRING,\n  step INT32\n)`;\n\n// ============================================================================\n// EMBEDDING TABLE SCHEMA\n// Separate table for vector storage to avoid copy-on-write overhead\n// ============================================================================\n\n/** Embedding vector dimensions. Default 384 (snowflake-arctic-embed-xs). */\nconst _rawDims = parseInt(process.env.GITNEXUS_EMBEDDING_DIMS ?? '384', 10);\nif (Number.isNaN(_rawDims) || _rawDims <= 0) {\n  throw new Error(\n    `GITNEXUS_EMBEDDING_DIMS must be a positive integer, got \"${process.env.GITNEXUS_EMBEDDING_DIMS}\"`,\n  );\n}\nexport const EMBEDDING_DIMS = _rawDims;\n\n/** HNSW vector index name for the CodeEmbedding table. */\nexport const EMBEDDING_INDEX_NAME = 'code_embedding_idx';\n\n/**\n * Sentinel value for \"no content hash available\" — used in legacy DBs and null rows.\n * Nodes with this hash are always treated as stale and re-embedded.\n */\nexport const STALE_HASH_SENTINEL = '';\n\nexport const EMBEDDING_SCHEMA = `\nCREATE NODE TABLE ${EMBEDDING_TABLE_NAME} (\n  id STRING,\n  nodeId STRING,","sourceCodeStart":581,"sourceCodeEnd":617,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/lbug/schema.ts#L581-L617","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before — non-integer value\nexport GITNEXUS_EMBEDDING_DIMS=384px\n# after — positive integer\nexport GITNEXUS_EMBEDDING_DIMS=384","handlingStrategy":"validation","validationCode":"// Validate GITNEXUS_EMBEDDING_DIMS before importing schema.ts\nconst rawDims = process.env.GITNEXUS_EMBEDDING_DIMS;\nif (rawDims !== undefined) {\n  const parsed = parseInt(rawDims, 10);\n  if (Number.isNaN(parsed) || parsed <= 0) {\n    throw new Error(`Invalid GITNEXUS_EMBEDDING_DIMS=\"${rawDims}\" — must be a positive integer`);\n  }\n}","typeGuard":"function isValidEmbeddingDims(value: string | undefined): value is string {\n  if (value === undefined) return true; // default is fine\n  const n = parseInt(value, 10);\n  return !Number.isNaN(n) && n > 0 && String(n) === value.trim();\n}","tryCatchPattern":"// This is a module-load-time error — wrap the import in a try-catch\n// in the entry point to give a friendlier message\ntry {\n  await import('./schema');\n} catch (e) {\n  if (e instanceof Error && e.message.includes('GITNEXUS_EMBEDDING_DIMS')) {\n    console.error('Configuration error:', e.message);\n    console.error('Set GITNEXUS_EMBEDDING_DIMS to a positive integer (e.g. 384) or unset it.');\n    process.exit(1);\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["configuration","env-var","embeddings","schema","validation","fail-fast"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}