abhigyanpatwari/GitNexus · error · GitNexusRcError

must be a number or numeric string.

Error message

${source} must be a number or numeric string.

What it means

Numeric-string options accept exactly a JSON number or a string; any other JSON type (boolean, null, object, array) reaches the fall-through throw at the end of the 'numeric-string' case. The message names the key (${source}) so you know which option has the wrong type.

Solutions

1. Replace the value with a number or numeric string: {"workers": 8}
2. Check the message's key name to find the exact offending option
3. Validate .gitnexusrc against the documented schema (number or string for these seven keys) before running analyze

Example fix

// before (.gitnexusrc)
{"workers": {"value": 8}}
// after
{"workers": 8}

for (const k of NUMERIC_KEYS) {
  const t = typeof rc[k];
  if (rc[k] !== undefined && t !== 'number' && t !== 'string') {
    throw new Error(`${k} must be a number or numeric string, got ${t}`);
  }
}

const isNumericOptionValue = (v: unknown): v is number | string =>
  typeof v === 'number' || typeof v === 'string';

catch (err) {
  if (err instanceof GitNexusRcError && err.message.includes('number or numeric string')) {
    // the key name in the message is the one with a boolean/null/object/array value
  }
}

When it happens

Trigger: {"workers": true}, {"maxFileSize": null}, {"embeddingBatchSize": [8]}, or {"workerTimeout": {"value": 30}} in .gitnexusrc; also applies inside the nested "analyze" block.

Common situations: Assuming numeric flags accept booleans ("workers": true meaning 'auto'); nesting values an extra level; YAML-to-JSON conversion producing a nested map where a scalar was expected.

Related errors

• must contain a JSON object.
• " " must be a JSON object.
• : " " and " " both configure the same option; set only one.
• entries must all be strings.
• entries must not be empty.

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

Appendix: source

Thrown at gitnexus/src/cli/analyze-config.ts:294

    case 'numeric-string': {
      // Mirror Commander's contract: these options reach the existing CLI
      // validation as strings. Accept a JSON number or a string; normalize to a
      // string and let the downstream per-flag validation enforce ranges so the
      // error messages stay in one place.
      if (typeof value === 'number') {
        if (!Number.isFinite(value)) {
          throw new GitNexusRcError(`${source} must be a finite number.`);
        }
        return String(value);
      }
      if (typeof value === 'string') {
        const trimmed = value.trim();
        if (!trimmed) {
          throw new GitNexusRcError(`${source} must not be empty.`);
        }
        return trimmed;
      }
      throw new GitNexusRcError(`${source} must be a number or numeric string.`);
    }
    case 'embeddings': {
      // Mirror `--embeddings [limit]`: boolean toggles, a non-negative integer
      // sets the node cap (normalized to a string, as Commander would supply).
      if (typeof value === 'boolean') return value;
      if (typeof value === 'number') {
        if (!Number.isInteger(value) || value < 0) {
          throw new GitNexusRcError(
            `${source} must be true/false or a non-negative integer (node cap; 0 disables the cap).`,
          );
        }
        return String(value);
      }
      throw new GitNexusRcError(
        `${source} must be a boolean or a non-negative integer (node cap; 0 disables the cap).`,
      );
    }
    default:

View on GitHub (pinned to ac9a4e9abd)