What causes "must not contain whitespace or control characters" in abhigyanpatwari/GitNexus?

Replace spaces in the branch name with the real git separator '-', e.g. feature/login-flow.

abhigyanpatwari/GitNexus · error · Error

must not contain whitespace or control characters

Error message

must not contain whitespace or control characters

What it means

Branch names are used verbatim in git ref arguments, so validateAutoSyncBranchName rejects any branch containing whitespace (spaces, tabs, newlines) or ASCII control characters (0x00-0x1F, 0x7F). Such values cannot be valid git refs and could split or inject into the shell command line, so the library throws before any git call.

Source

Thrown at gitnexus/src/core/auto-sync/config.ts:337

  const repoName = /\.git$/i.test(lastSegment) ? lastSegment.slice(0, -4) : lastSegment;
  if (
    !repoName ||
    repoName === '.' ||
    repoName === '..' ||
    repoName === 'unknown' ||
    repoName.startsWith('-') ||
    !REMOTE_REPO_NAME_PATTERN.test(repoName)
  ) {
    throw new Error(
      'repository name must use only letters, digits, ".", "_", or "-" and must not be "unknown"',
    );
  }
}

export function validateAutoSyncBranchName(branch: string): void {
  if (!branch.trim()) throw new Error('must not be empty');
  if (/[\s\0-\x1f\x7f]/.test(branch))
    throw new Error('must not contain whitespace or control characters');
  if (/[~^:?*[\\]/.test(branch)) throw new Error('contains characters not allowed in a git ref');
  if (branch.startsWith('-')) throw new Error('must not start with "-"');
  if (branch.startsWith('/')) throw new Error('must not start with "/"');
  if (branch.includes('..')) throw new Error('must not contain ".."');
  if (branch.includes('`')) throw new Error('must not contain backticks');
  if (branch.endsWith('/') || branch.endsWith('.')) throw new Error('must not end with "/" or "."');
  if (branch.includes('//')) throw new Error('must not contain consecutive slashes');
  if (branch.includes('@{')) throw new Error('must not contain "@{"');
  if (
    branch
      .split('/')
      .some(
        (component) =>
          component.startsWith('.') || component.endsWith('.') || component.endsWith('.lock'),
      )
  )
    throw new Error('must not contain hidden, trailing-dot, or .lock path components');
}

View on GitHub (pinned to 0d1aed942f)

Solutions

Replace spaces in the branch name with the real git separator '-', e.g. feature/login-flow.
Trim the value and ensure the config file uses LF or that trailing CR is stripped.
Re-check wherever the branch name is generated — strip control chars before writing config.
If the branch truly has a space (git disallows this), the value is wrong; find the actual ref with git branch --list.

Example fix

// before
branches:
  - "feature login flow"
// after
branches:
  - feature/login-flow

Defensive patterns

Strategy: validation

Validate before calling

function branchCharsOk(b) {
  return typeof b === 'string' && !/[\s\u0000-\u001f\u007f]/.test(b);
}
const bad = (cfg.branches ?? []).filter((b) => !branchCharsOk(b));
if (bad.length) throw new Error(`branches contain whitespace/control chars: ${JSON.stringify(bad)}`);

Type guard

function isCleanBranch(v) {
  return typeof v === 'string' && v === v.trim() && !/[\s\u0000-\u001f\u007f]/.test(v);
}

Try / catch

try {
  validateAutoSyncBranchName(branch);
} catch (e) {
  if (String(e.message).includes('whitespace or control')) {
    log.error(`Branch '${JSON.stringify(branch)}' has spaces/control characters; use hyphen-separated names.`);
  }
  throw e;
}

Prevention

Trim values read from env vars, CI outputs, and files before writing config.
Use hyphens, not spaces, in branch names (git requires this anyway).
Save config files with LF endings to avoid stray \r.
Sanitize branch names sourced from external systems (webhooks, CI logs).

When it happens

Trigger: branches: ["feature branch"] (space inside); branch value pasted with a trailing newline or tab; a branch name containing an ANSI escape or NUL from a bad script; unquoted YAML that swallowed surrounding text.

Common situations: Copy-pasting 'git checkout feature branch' style text; CI logs providing branch names with \r\n; config files edited on Windows with CRLF endings leaking \r into the value.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@0d1aed942f (2026-09-08). Data as JSON: /api/errors/8acd1fd99f590298. Report an issue: GitHub.