abhigyanpatwari/GitNexus · warning · GitNexusRcError

: branch name must not contain a backtick (it would break…

Error message

${source}: branch name must not contain a backtick (it would break the generated Markdown).

What it means

GITNEXUS_WAL_CHECKPOINT_THRESHOLD was set to a non-empty value that parseWalCheckpointThreshold rejects (must be an integer >= -1; -1 disables auto-checkpointing). The env path stays soft — GitNexus warns and falls back to the 64 MiB default — to preserve 'set once in your shell' ergonomics across mixed-version invocations, while the equivalent CLI flag --wal-checkpoint-threshold hard-errors on the same input.

Solutions

Set a plain integer of bytes: GITNEXUS_WAL_CHECKPOINT_THRESHOLD=134217728 (128 MiB)
Use -1 only to disable auto-checkpointing
Drop the var to accept the 64 MiB default
Prefer the CLI flag --wal-checkpoint-threshold when you want invalid input to fail loudly

Example fix

# before
export GITNEXUS_WAL_CHECKPOINT_THRESHOLD=64MB   # unparseable -> silent 64 MiB default

# after
export GITNEXUS_WAL_CHECKPOINT_THRESHOLD=134217728   # plain integer bytes (128 MiB)

Defensive patterns

Strategy: validation

Validate before calling

// validate before the process starts using it
const raw = process.env.GITNEXUS_WAL_CHECKPOINT_THRESHOLD;
if (raw !== undefined && raw.trim() !== '') {
  const n = Number(raw);
  if (!Number.isInteger(n) || n < -1) {
    throw new Error(
      `GITNEXUS_WAL_CHECKPOINT_THRESHOLD must be an integer >= -1 (bytes; -1 disables), got: ${raw}`,
    );
  }
}

Type guard

const isValidWalThreshold = (raw: string | undefined): boolean => {
  if (raw === undefined || raw.trim() === '') return true;
  const n = Number(raw);
  return Number.isInteger(n) && n >= -1;
};

Prevention

Write byte values as plain integers in env vars — never unit suffixes
Use the CLI flag when you want malformed values to fail loudly instead of soft-falling-back
Smoke-test env templates once at deploy time, not per-run

When it happens

Trigger: Number(raw) is NaN, fractional, or < -1 for a non-empty trimmed value — e.g. GITNEXUS_WAL_CHECKPOINT_THRESHOLD="64MB", "0.5", "-2", or "64_000_000".

Common situations: Writing a byte value with a unit suffix; copying a CLI-flag-style value into an env var; shell quoting/whitespace mistakes; scripts generated for a different tool version expecting a different format.

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@52924ef12c (2026-08-20). Data as JSON: /api/errors/b9cd3b29a0e9f1ae. Report an issue: GitHub.

Appendix: source

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

  if (/[~^:?*[\\]/.test(trimmed)) {
    throw new GitNexusRcError(
      `${source}: branch name contains characters not allowed in a git ref (~ ^ : ? * [ \\).`,
    );
  }
  if (trimmed.startsWith('-')) {
    throw new GitNexusRcError(`${source}: branch name must not start with "-".`);
  }
  if (trimmed.includes('..')) {
    throw new GitNexusRcError(`${source}: branch name must not contain "..".`);
  }
  // Git permits a backtick in a ref, but the branch is embedded inside a
  // Markdown inline-code span in the generated AGENTS.md/CLAUDE.md regression
  // example, where a backtick would close the span early and let the rest of
  // the template render as instruction text. Reject it at this single
  // chokepoint so all three tiers (CLI flag, .gitnexusrc, auto-detect via
  // sanitizeDetectedBranch) are covered (#1996 tri-review P1).
  if (trimmed.includes('`')) {
    throw new GitNexusRcError(
      `${source}: branch name must not contain a backtick (it would break the generated Markdown).`,
    );
  }
  return trimmed;
}

/**
 * Best-effort validation for an auto-detected branch (from git). Never throws —
 * returns `undefined` for anything unusable so the resolver falls back to the
 * next precedence tier.
 */
export function sanitizeDetectedBranch(value: string | null | undefined): string | undefined {
  if (!value) return undefined;
  try {
    return validateBranchName(value, 'detected branch');
  } catch {
    return undefined;
  }

View on GitHub (pinned to 52924ef12c)