abhigyanpatwari/GitNexus · error · Error

must not be empty

Error message

must not be empty

What it means

validateAutoSyncBranchName rejects an empty or whitespace-only branch name as the first check. Auto-sync needs a concrete branch to fetch/checkout; an empty value would produce a broken git command, so the library fails fast at config parse time via parseAutoSyncConfig.

Source

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

  // strict superset, so anything accepted here is accepted there.
  const lastSegment = pathParts[pathParts.length - 1];
  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'),
      )
  )

View on GitHub (pinned to 0d1aed942f)

Solutions

  1. Set the branch to a real branch name, e.g. branches: ["main"].
  2. Delete the empty entry from the branches list instead of leaving a placeholder.
  3. If the branch comes from a variable/env value, verify it is set before starting auto-sync.
  4. Trim the value — whitespace-only strings count as empty.

Example fix

// before
branches:
  - ""
// after
branches:
  - main
Defensive patterns

Strategy: validation

Validate before calling

function branchNonEmpty(b) {
  return typeof b === 'string' && b.trim().length > 0;
}
const branches = (cfg.branches ?? []).filter(branchNonEmpty);
if (branches.length === 0) throw new Error('at least one non-empty branch is required');

Type guard

function isNonEmptyBranch(v) {
  return typeof v === 'string' && v.trim() !== '';
}

Try / catch

try {
  const cfg = parseAutoSyncConfig(raw);
} catch (e) {
  if (String(e.message) === 'must not be empty') {
    log.error('A branches[] entry is empty; provide a real branch name like "main".');
  }
  throw e;
}

Prevention

When it happens

Trigger: branches: [""] or branches: [" "] in the auto-sync config; a template/variable that failed to interpolate leaving an empty string; a YAML list entry that is only whitespace or a stray '- ' item.

Common situations: Generated config where the branch env var was unset; copy-pasted YAML with an empty bullet; refactoring that removed the branch name but left the list entry.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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