{"record":{"id":"fa7597394a98a712","repo":"abhigyanpatwari/GitNexus","slug":"gitnexus-embedding-dims-must-be-a-positive-integer","errorCode":null,"errorMessage":"GITNEXUS_EMBEDDING_DIMS must be a positive integer, got \"${rawDims}\"","messagePattern":"GITNEXUS_EMBEDDING_DIMS must be a positive integer, got \"(.+?)\"","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/embeddings/http-client.ts","lineNumber":158,"sourceCode":"\n/**\n * Build config from the current process.env snapshot.\n * Returns null when GITNEXUS_EMBEDDING_URL + GITNEXUS_EMBEDDING_MODEL are unset.\n * Not cached — env vars are read fresh so late configuration takes effect.\n * Validates GITNEXUS_EMBEDDING_DIMS and throws on a malformed value; callers\n * that only need to know whether HTTP mode is *configured* must use\n * {@link isHttpMode} (a presence probe that never throws), not this.\n */\nconst readConfig = (): HttpConfig | null => {\n  const baseUrl = process.env.GITNEXUS_EMBEDDING_URL;\n  const model = process.env.GITNEXUS_EMBEDDING_MODEL;\n  if (!baseUrl || !model) return null;\n\n  const rawDims = process.env.GITNEXUS_EMBEDDING_DIMS;\n  let dimensions: number | undefined;\n  if (rawDims !== undefined) {\n    if (!/^\\d+$/.test(rawDims)) {\n      throw new Error(`${EMBEDDING_DIMS_ENV_ERROR_LEAD}, got \"${rawDims}\"`);\n    }\n    const parsed = parseInt(rawDims, 10);\n    if (parsed <= 0) {\n      throw new Error(`${EMBEDDING_DIMS_ENV_ERROR_LEAD}, got \"${rawDims}\"`);\n    }\n    dimensions = parsed;\n  }\n\n  const rawRequestDims = process.env.GITNEXUS_EMBEDDING_REQUEST_DIMS?.trim();\n  let requestDimensions = dimensions;\n  if (rawRequestDims) {\n    if (/^(omit|none|off|false|0)$/i.test(rawRequestDims)) {\n      requestDimensions = undefined;\n    } else {\n      if (!/^\\d+$/.test(rawRequestDims)) {\n        throw new Error(`${EMBEDDING_REQUEST_DIMS_ENV_ERROR_LEAD}, got \"${rawRequestDims}\"`);\n      }\n      const parsed = parseInt(rawRequestDims, 10);","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/embeddings/http-client.ts#L140-L176","documentation":"Thrown by readConfig() in http-client.ts when GITNEXUS_EMBEDDING_DIMS is set but is not a string of digits, or parses to a non-positive integer. GITNEXUS_EMBEDDING_DIMS declares the vector dimensionality of the HTTP endpoint's model so the local index can be sized correctly; a malformed value would create a dimension mismatch at query time. The error lead is generated by dimsEnvErrorLead('GITNEXUS_EMBEDDING_DIMS') so the CLI's isHttpEmbeddingDimsError() can recognize it and print a clean config message instead of a stack dump (#2385).","triggerScenarios":"readConfig() at http-client.ts:154-165, invoked whenever HTTP mode is active (both GITNEXUS_EMBEDDING_URL and GITNEXUS_EMBEDDING_MODEL set). Fires on e.g. GITNEXUS_EMBEDDING_DIMS=384d, =-1, =1.5, =auto, =0. Note: getHttpDimensions() also calls readConfig(), so merely reading dimensions surfaces this.","commonSituations":"Adding a unit suffix (384d, 1536-d); a negative or zero from a miscomputed config; a non-numeric placeholder (auto) copy-pasted from a model card; setting dims that don't match the endpoint model (this error only catches malformed strings, not wrong-but-valid dims).","solutions":["Set GITNEXUS_EMBEDDING_DIMS to a positive integer matching your model's vector size, e.g. 1536 for text-embedding-3-small.","Unset it to fall back to DEFAULT_DIMS (384) — only correct if your model happens to be 384-dim.","Verify the value against the endpoint's documentation before retrying."],"exampleFix":"# before\nexport GITNEXUS_EMBEDDING_DIMS=1536d\n# after\nexport GITNEXUS_EMBEDDING_DIMS=1536","handlingStrategy":"validation","validationCode":"const v = process.env.GITNEXUS_EMBEDDING_DIMS;\nif (v !== undefined) {\n  if (!/^\\d+$/.test(v) || parseInt(v, 10) <= 0) {\n    throw new Error('GITNEXUS_EMBEDDING_DIMS must be a positive integer matching the model vector size.');\n  }\n}","typeGuard":"const isValidDims = (v: string | undefined): boolean =>\n  v === undefined || (/^\\d+$/.test(v) && parseInt(v, 10) > 0);","tryCatchPattern":"import { isHttpEmbeddingDimsError } from 'gitnexus/src/core/embeddings/http-client.js';\ntry {\n  // any operation that triggers readConfig(), e.g. isHttpMode-then-httpEmbed\n  await embedText(text);\n} catch (err) {\n  const msg = err instanceof Error ? err.message : String(err);\n  if (isHttpEmbeddingDimsError(msg)) {\n    console.error('Fix GITNEXUS_EMBEDDING_DIMS to a positive integer and retry.');\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["Set GITNEXUS_EMBEDDING_DIMS to a bare positive integer matching the endpoint model's vector size.","Unset it to fall back to 384 (only correct for 384-dim models).","Validate the value against the model card before running analyze."],"tags":["config","env-var","embeddings","http-mode","validation","dimensions"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}