abhigyanpatwari/GitNexus · error · Error

repository name must use only letters, digits, ".", "_", or

Error message

repository name must use only letters, digits, ".", "_", or "-" and must not be "unknown"

What it means

The final path segment of the remote URL becomes the on-disk clone directory name, so validateAutoSyncRemoteUrl applies strict name rules: after stripping a trailing .git, the repo name must match REMOTE_REPO_NAME_PATTERN ([A-Za-z0-9._-]) and must not be empty, '.', '..', 'unknown', or start with '-'. This error means the repo name violates those rules. Unlike the looser path check, this is enforced strictly to keep the clone directory safe and predictable.

Source

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

  ) {
    throw new Error('path must include owner/repo without traversal');
  }
  // The final segment becomes the on-disk clone directory via `extractRepoName`,
  // whose name rules are stricter than the path check above: a backslash — or
  // anything outside `[A-Za-z0-9._-]` — passes here and then throws once per
  // tick inside the sync loop instead of at config load. These rules are a
  // 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 (

View on GitHub (pinned to 0d1aed942f)

Solutions

Rename the repository on the forge to use only letters, digits, '.', '_', and '-'.
Fix the URL so the final segment is the actual repo name with no trailing slash.
Use the repo's .git suffix form (git@github.com:acme/repo.git) — the suffix is stripped before validation.
If the repo is genuinely named 'unknown' or starts with '-', rename it; those exact values are reserved by the library.
Ensure no URL-encoding or shell artifacts (%20, ~) remain in the config value.

Example fix

// before
remote_url = git@github.com:acme/my repo+tools.git
// after
remote_url = git@github.com:acme/my-repo-tools.git

Defensive patterns

Strategy: validation

Validate before calling

const NAME_RE = /^[A-Za-z0-9._-]+$/;
function repoNameOk(url) {
  const m = /^git@[^:\s/]+:(\S+)$/.exec((url ?? '').trim());
  if (!m) return false;
  let last = m[1].split('/').pop();
  if (/\.git$/i.test(last)) last = last.slice(0, -4);
  return !!last && !['.', '..', 'unknown'].includes(last) && !last.startsWith('-') && NAME_RE.test(last);
}
if (!repoNameOk(cfg.remote_url)) throw new Error('repo name must match [A-Za-z0-9._-] and not be "unknown"');

Try / catch

try {
  validateAutoSyncRemoteUrl(remoteUrl);
} catch (e) {
  if (String(e.message).includes('repository name must use only')) {
    log.error(`Repo name from '${remoteUrl}' is not a safe directory name; rename the repo or fix the URL.`);
  }
  throw e;
}

Prevention

Keep repo names restricted to letters, digits, '.', '_', '-'.
Avoid renaming repos to values with '+', '~', or unicode characters if auto-sync is used.
Never use 'unknown' as a repo name; it is a reserved sentinel.
Strip trailing slashes and whitespace before saving the URL.

When it happens

Trigger: remote URL whose last segment contains characters like '+', '~', '%', non-ASCII letters, or a backslash (git@github.com:acme/my~repo.git); a repo literally named 'unknown' (git@github.com:acme/unknown.git); a name starting with '-' (git@github.com:acme/-weird.git); or a URL ending in '/' leaving an empty name.

Common situations: Repo renamed on the forge to a name with unusual characters; URL truncated so the name is missing; pasting a URL that ends with a slash;placeholder 'unknown' left in generated config by another tool.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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