What causes "${name} must be a positive integer, got "${value}"" in abhigyanpatwari/GitNexus?

Set a positive integer: export GITNEXUS_EMBEDDING_BATCH_SIZE=32.

must be a positive integer, got

Error message

${name} must be a positive integer, got "${value}"

What it means

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.

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.

Example fix

# before
export GITNEXUS_EMBEDDING_BATCH_SIZE=   # empty from an unset shell var
npx gitnexus analyze --embeddings
# GITNEXUS_EMBEDDING_BATCH_SIZE must be a positive integer, got ""

# after
export GITNEXUS_EMBEDDING_BATCH_SIZE=32   # or: unset GITNEXUS_EMBEDDING_BATCH_SIZE
npx gitnexus analyze --embeddings

Defensive patterns

Strategy: validation

Validate before calling

// Validate integer env settings before starting the CLI:
function positiveIntEnv(name: string): boolean {
  const v = process.env[name];
  if (v === undefined) return true;
  const n = Number(v);
  return Number.isInteger(n) && n > 0;
}
for (const name of ['GITNEXUS_EMBEDDING_BATCH_SIZE']) {
  if (!positiveIntEnv(name)) throw new Error(`${name} must be a positive integer`);
}

Try / catch

try {
  await runWithEmbeddings();
} catch (err) {
  const m = /(GITNEXUS_\w+) must be a positive integer, got "(.*)"/.exec(String((err as Error).message));
  if (m) {
    delete process.env[m[1]]; // fall back to the default
    return runWithEmbeddings();
  }
  throw err;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@aac7515d2a (2026-08-20). Data as JSON: /api/errors/2840e340beacda45. Report an issue: GitHub.

Appendix: source

Thrown at gitnexus/src/core/embeddings/config.ts:55

      `  GITNEXUS_VECTOR_MAX_DISTANCE must be a positive number in (0, ${VECTOR_MAX_DISTANCE_CEILING}], got "${raw}" — using default ${fallback}`,
    );
    return fallback;
  }
  if (parsed > VECTOR_MAX_DISTANCE_CEILING) {
    warnOnce(
      `clamp:${raw}`,
      `  GITNEXUS_VECTOR_MAX_DISTANCE=${parsed} exceeds the cosine-distance ceiling (${VECTOR_MAX_DISTANCE_CEILING}) — clamping`,
    );
    return VECTOR_MAX_DISTANCE_CEILING;
  }
  return parsed;
};

const parsePositiveInt = (name: string, value: string | undefined, fallback: number): number => {
  if (value === undefined) return fallback;
  const parsed = Number(value);
  if (!Number.isInteger(parsed) || parsed <= 0) {
    throw new Error(`${name} must be a positive integer, got "${value}"`);
  }
  return parsed;
};

const parseDevice = (value: string | undefined): EmbeddingConfig['device'] | undefined => {
  if (value === undefined) return undefined;
  if (
    value === 'auto' ||
    value === 'dml' ||
    value === 'cuda' ||
    value === 'cpu' ||
    value === 'wasm'
  ) {
    return value;
  }
  throw new Error(`embedding device must be one of auto, dml, cuda, cpu, wasm; got "${value}"`);
};

View on GitHub (pinned to aac7515d2a)