{"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":160,"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":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/ac9a4e9abd8fd3058c070b72c23402a4f887929a/gitnexus/src/core/embeddings/http-client.ts#L142-L178","documentation":"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).","triggerScenarios":"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.","commonSituations":"Copying 'nq8d' style model names into DIMS, quotes/whitespace from .env, or setting dims when the endpoint ignores/derives them itself.","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."],"exampleFix":"# before\nexport GITNEXUS_EMBEDDING_DIMS='768d'\n# after\nexport GITNEXUS_EMBEDDING_DIMS=768","handlingStrategy":"validation","validationCode":"const dims = process.env.GITNEXUS_EMBEDDING_DIMS;\nif (dims !== undefined && dims !== '' && !/^\\d+$/.test(dims)) {\n  throw new Error(`Bad GITNEXUS_EMBEDDING_DIMS: \"${dims}\"`);\n}","typeGuard":"const isDimsEnvError = (e: unknown): boolean =>\n  e instanceof Error && e.message.includes('GITNEXUS_EMBEDDING_DIMS must be');","tryCatchPattern":"try {\n  await httpEmbed(texts);\n} catch (e) {\n  if (isDimsEnvError(e)) { /* fix/unset GITNEXUS_EMBEDDING_DIMS; non-retryable */ }\n  else throw e;\n}","preventionTips":["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."],"tags":["embeddings","environment-variable","configuration","validation","dimensions"],"backgroundTag":"invalid-env-var","analyzedSha":"ac9a4e9abd8fd3058c070b72c23402a4f887929a","analyzedAt":"2026-08-20T23:29:22.980Z","contentChangedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}