{"record":{"id":"2840e340beacda45","repo":"abhigyanpatwari/GitNexus","slug":"name-must-be-a-positive-integer-got-value","errorCode":null,"errorMessage":"${name} must be a positive integer, got \"${value}\"","messagePattern":"(.+?) must be a positive integer, got \"(.+?)\"","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/embeddings/config.ts","lineNumber":55,"sourceCode":"      `  GITNEXUS_VECTOR_MAX_DISTANCE must be a positive number in (0, ${VECTOR_MAX_DISTANCE_CEILING}], got \"${raw}\" — using default ${fallback}`,\n    );\n    return fallback;\n  }\n  if (parsed > VECTOR_MAX_DISTANCE_CEILING) {\n    warnOnce(\n      `clamp:${raw}`,\n      `  GITNEXUS_VECTOR_MAX_DISTANCE=${parsed} exceeds the cosine-distance ceiling (${VECTOR_MAX_DISTANCE_CEILING}) — clamping`,\n    );\n    return VECTOR_MAX_DISTANCE_CEILING;\n  }\n  return parsed;\n};\n\nconst parsePositiveInt = (name: string, value: string | undefined, fallback: number): number => {\n  if (value === undefined) return fallback;\n  const parsed = Number(value);\n  if (!Number.isInteger(parsed) || parsed <= 0) {\n    throw new Error(`${name} must be a positive integer, got \"${value}\"`);\n  }\n  return parsed;\n};\n\nconst parseDevice = (value: string | undefined): EmbeddingConfig['device'] | undefined => {\n  if (value === undefined) return undefined;\n  if (\n    value === 'auto' ||\n    value === 'dml' ||\n    value === 'cuda' ||\n    value === 'cpu' ||\n    value === 'wasm'\n  ) {\n    return value;\n  }\n  throw new Error(`embedding device must be one of auto, dml, cuda, cpu, wasm; got \"${value}\"`);\n};\n","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/embeddings/config.ts#L37-L73","documentation":"Thrown by parsePositiveInt() in config.ts when an embedding config integer env var (GITNEXUS_EMBEDDING_BATCH_SIZE, GITNEXUS_EMBEDDING_SUB_BATCH_SIZE, or GITNEXUS_EMBEDDING_THREADS) is present but Number(value) is not an integer or is <= 0. The embedding pipeline needs positive integer batch/thread counts to size ONNX sessions and chunk Cypher writes; a zero/negative/fractional value would produce empty batches or undefined threading. Unlike the vector-distance parser (which warns-and-clamps), integer config is strict because there is no safe clamp.","triggerScenarios":"resolveEmbeddingConfig() calls parsePositiveInt for the three env vars at config.ts:81-95. Fires on e.g. GITNEXUS_EMBEDDING_BATCH_SIZE=0, =2.5, =-1, =abc, or an empty-ish non-undefined value. The analyze command and the MCP embedder both resolve config before model load.","commonSituations":"Setting GITNEXUS_EMBEDDING_THREADS=0 thinking it means auto (it does not — auto is the unset default); copy-pasting a float batch size from docs; a shell script exporting a computed value that evaluated to empty or 0; setting a value with a unit suffix like 4x.","solutions":["Set the named env var to a positive whole number, e.g. GITNEXUS_EMBEDDING_BATCH_SIZE=32.","Unset the variable to accept the built-in default (batchSize/subBatchSize from DEFAULT_EMBEDDING_CONFIG, threads from defaultEmbeddingThreads()).","For thread count, leave it unset rather than 0 — auto-detection only runs when the var is undefined."],"exampleFix":"// before\nexport GITNEXUS_EMBEDDING_THREADS=0\n// after — omit for auto, or set a real positive integer\nunset GITNEXUS_EMBEDDING_THREADS\n# or\nexport GITNEXUS_EMBEDDING_THREADS=4","handlingStrategy":"validation","validationCode":"// Validate embedding integer env vars before resolving config.\nconst assertPositiveIntEnv = (name: string): void => {\n  const v = process.env[name];\n  if (v === undefined) return;\n  const n = Number(v);\n  if (!Number.isInteger(n) || n <= 0) {\n    throw new Error(`${name} must be a positive integer; unset it or use a whole number > 0.`);\n  }\n};\n['GITNEXUS_EMBEDDING_BATCH_SIZE', 'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE', 'GITNEXUS_EMBEDDING_THREADS']\n  .forEach(assertPositiveIntEnv);","typeGuard":"const isPositiveInt = (v: string | undefined): boolean =>\n  v === undefined || (Number.isInteger(Number(v)) && Number(v) > 0);","tryCatchPattern":"try {\n  resolveEmbeddingConfig();\n} catch (err) {\n  if (err instanceof Error && /must be a positive integer/.test(err.message)) {\n    console.error('Bad embedding config:', err.message, '— unsetting and retrying with defaults.');\n    delete process.env.GITNEXUS_EMBEDDING_BATCH_SIZE; // etc.\n  }\n  throw err;\n}","preventionTips":["Use only positive whole numbers for the three integer embedding env vars.","Leave GITNEXUS_EMBEDDING_THREADS unset for auto-detection (0 does not mean auto).","Validate env vars in a preflight check before running analyze in CI."],"tags":["config","env-var","embeddings","validation"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}