abhigyanpatwari/GitNexus · error

${allowedRaw.key} must not be blank.

Error message

${allowedRaw.key} must not be blank.

What it means

Thrown by parseRepositoryPolicy when GITNEXUS_MCP_ALLOWED_REPOS is defined but contains no usable entries. The value is split on commas, each entry trimmed, and empty entries filtered out; if nothing survives, the allowlist variable is effectively blank and the server refuses to start rather than silently allowing nothing (or everything). The message names the exact offending variable key.

Source

Thrown at gitnexus/src/mcp/repository-policy.ts:42

function configuredValue(
  env: NodeJS.ProcessEnv,
  key: string,
): { key: string; value: string } | undefined {
  const value = env[key];
  return value === undefined ? undefined : { key, value };
}

function parseRepositoryPolicy(env: NodeJS.ProcessEnv): RawRepositoryPolicy {
  const allowedRaw = configuredValue(env, CANONICAL_ALLOWED);
  const defaultRaw = configuredValue(env, CANONICAL_DEFAULT);

  let allowed: string[] | undefined;
  if (allowedRaw) {
    allowed = allowedRaw.value
      .split(',')
      .map((entry) => entry.trim())
      .filter(Boolean);
    if (allowed.length === 0) throw new Error(`${allowedRaw.key} must not be blank.`);
  }

  let defaultRepo: string | undefined;
  if (defaultRaw) {
    defaultRepo = defaultRaw.value.trim();
    if (!defaultRepo) throw new Error(`${defaultRaw.key} must not be blank.`);
  }

  return { allowed, defaultRepo };
}

function normalizedPath(value: string): string {
  const resolved = path.resolve(value);
  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
}

function isAbsolutePath(value: string): boolean {
  return path.isAbsolute(value) || path.win32.isAbsolute(value);

View on GitHub (pinned to 52924ef12c)

Solutions

1. Set the variable to a comma-separated list of repository names or absolute paths with at least one real entry, e.g. GITNEXUS_MCP_ALLOWED_REPOS='frontend,backend'.
2. If you did not intend an allowlist, remove the variable from the environment instead of leaving a placeholder.
3. Verify what the process actually sees: print process.env.GITNEXUS_MCP_ALLOWED_REPOS.length and its JSON representation from the server context.

Example fix

# before
export GITNEXUS_MCP_ALLOWED_REPOS="$REPOS"   # REPOS unset -> blank

# after
export GITNEXUS_MCP_ALLOWED_REPOS="frontend,backend"

const rawAllowed = process.env.GITNEXUS_MCP_ALLOWED_REPOS;
if (rawAllowed !== undefined) {
  const entries = rawAllowed.split(',').map((s) => s.trim()).filter(Boolean);
  if (entries.length === 0) {
    throw new Error('GITNEXUS_MCP_ALLOWED_REPOS is blank — set a real list or unset it.');
  }
}

const hasValidAllowlistEnv = (v: string | undefined): boolean =>
  v === undefined || v.split(',').some((s) => s.trim().length > 0);

When it happens

Trigger: Setting GITNEXUS_MCP_ALLOWED_REPOS=',', ' , ', ',,,', or a value made only of whitespace. Note an unset variable is fine; an empty string value also passes this check but yields no restriction only when combined with no default — the blank-comma case is the hard failure.

Common situations: A deploy script exports the variable from an empty shell variable: GITNEXUS_MCP_ALLOWED_REPOS="$REPOS" where REPOS is unset-but-quoted becomes ''. More commonly, a YAML/CI env block has a placeholder like 'repo1, ' with the real list never substituted, or a trailing/duplicate commas-only value survives templating.

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

• ${source} must be a positive integer.
• GITNEXUS_MCP_READ_ONLY must be 0 or 1.
• ${defaultRaw.key} must not be blank.
• Group routing is unavailable when an MCP repository allowlis
• Group tools are unavailable when an MCP repository allowlist

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