{"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":"exception","errorClass":null,"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/aac7515d2a8c50a1f8f923c6fb77218b333560d6/gitnexus/src/core/embeddings/config.ts#L37-L73","documentation":"resolveEmbeddingConfig() parses integer-valued embedding settings from environment variables (e.g. GITNEXUS_EMBEDDING_BATCH_SIZE) with parsePositiveInt. A value that Number() does not report as an integer > 0 — zero, negatives, floats, non-numeric strings, empty string, NaN — throws with the variable name and offending value. Unlike the distance setting, which clamps, integer settings fail fast.","triggerScenarios":"Setting GITNEXUS_EMBEDDING_BATCH_SIZE=0, =-4, =2.5, =abc, or = (empty) in the environment and then calling resolveEmbeddingConfig() — directly or via any embeddings path (analyze --embeddings, MCP embedder). Number(value) then fails the Number.isInteger(parsed) || parsed > 0 check.","commonSituations":"CI templates copying a 0 default, arithmetic in shell scripts producing empty strings (BATCH=; BATCH=${BATCH:-32} mistakes), YAML env maps quoting numbers oddly, or users tuning batch size with a float like 8.0 on some shells/versions.","solutions":["Set a positive integer: export GITNEXUS_EMBEDDING_BATCH_SIZE=32.","Unset the variable to fall back to the default (16).","Check for accidental empty assignment in scripts: echo \"[$GITNEXUS_EMBEDDING_BATCH_SIZE]\" should not print [].","Avoid decimals and unit suffixes; the parser accepts only integer spellings."],"exampleFix":"# before\nexport GITNEXUS_EMBEDDING_BATCH_SIZE=   # empty from an unset shell var\nnpx gitnexus analyze --embeddings\n# GITNEXUS_EMBEDDING_BATCH_SIZE must be a positive integer, got \"\"\n\n# after\nexport GITNEXUS_EMBEDDING_BATCH_SIZE=32   # or: unset GITNEXUS_EMBEDDING_BATCH_SIZE\nnpx gitnexus analyze --embeddings","handlingStrategy":"validation","validationCode":"// Validate integer env settings before starting the CLI:\nfunction positiveIntEnv(name: string): boolean {\n  const v = process.env[name];\n  if (v === undefined) return true;\n  const n = Number(v);\n  return Number.isInteger(n) && n > 0;\n}\nfor (const name of ['GITNEXUS_EMBEDDING_BATCH_SIZE']) {\n  if (!positiveIntEnv(name)) throw new Error(`${name} must be a positive integer`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runWithEmbeddings();\n} catch (err) {\n  const m = /(GITNEXUS_\\w+) must be a positive integer, got \"(.*)\"/.exec(String((err as Error).message));\n  if (m) {\n    delete process.env[m[1]]; // fall back to the default\n    return runWithEmbeddings();\n  }\n  throw err;\n}","preventionTips":["Echo env vars with delimiters (echo \"[$VAR]\") when scripting to catch empty values.","Use integer literals only — no decimals, units, or trailing spaces.","Unset rather than zero-fill when you want defaults.","Keep a single documented list of GitNexus env vars with expected types in your runbooks."],"tags":["embeddings","environment-variable","config-validation","batch-size"],"backgroundTag":"invalid-env-var-value","analyzedSha":"aac7515d2a8c50a1f8f923c6fb77218b333560d6","analyzedAt":"2026-08-20T23:29:22.980Z","contentChangedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}