Specify an explicit repo because multiple repositories are a

Error message

Specify an explicit repo because multiple repositories are allowed.

What it means

Thrown by McpRepositoryPolicy.repoForArgs when a repository allowlist with more than one entry is configured, the call provides no explicit repo argument, and no GITNEXUS_MCP_DEFAULT_REPO is set. With multiple allowed repositories the server cannot pick one for you, so it refuses the ambiguous call instead of guessing.

Source

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

  }

  private repoForArgs(args: Record<string, unknown> | undefined): ResolvedRepository | undefined {
    const explicit = args?.repo;
    if (explicit !== undefined) {
      if (typeof explicit !== 'string') throw unavailableRepositoryError();
      if (explicit.trim().startsWith('@')) {
        if (this.restricted) {
          throw new Error('Group routing is unavailable when an MCP repository allowlist is set.');
        }
        return undefined;
      }
      return this.resolveRuntimeRepo(explicit);
    }

    if (this.defaultRepo) return this.defaultRepo;
    if (this.restricted && this.allowed.length === 1) return this.allowed[0];
    if (this.restricted && this.allowed.length > 1) {
      throw new Error('Specify an explicit repo because multiple repositories are allowed.');
    }
    return undefined;
  }

  private normalizeToolArgs(
    args: Record<string, unknown> | undefined,
  ): Record<string, unknown> | undefined {
    if (!this.configured) return args;
    if (!this.restricted && args?.repo !== undefined) return args;
    const selected = this.repoForArgs(args);
    if (!selected) return args;
    return { ...(args ?? {}), repo: selected.path };
  }

  private async listAllowedRepos(backend: LocalBackend): Promise<RepoListing[]> {
    const current = await backend.listRepos();
    if (!this.restricted) return current;
    return current

View on GitHub (pinned to 52924ef12c)

Solutions

Include an explicit repo in every tool call: { search_query: 'auth', repo: 'frontend' }.
Set GITNEXUS_MCP_DEFAULT_REPO to one of the allowed repositories to restore repo-optional calls.
If only one repo should be served, reduce GITNEXUS_MCP_ALLOWED_REPOS to that single entry — it is then auto-selected.

Example fix

# before
await client.callTool({ name: 'query', arguments: { search_query: 'auth' } });

# after
await client.callTool({ name: 'query', arguments: { search_query: 'auth', repo: 'frontend' } });
# or server env: GITNEXUS_MCP_DEFAULT_REPO=frontend

Defensive patterns

Strategy: validation

Validate before calling

// Before calling tools when an allowlist may be set:
if (allowlistCount > 1 && !defaultRepoConfigured && args.repo === undefined) {
  throw new Error('Multiple repos allowed and no default — pass an explicit repo argument.');
}

Type guard

const hasExplicitRepo = (args: Record<string, unknown> | undefined): boolean =>
  typeof args?.repo === 'string' && args.repo.trim().length > 0;

Try / catch

try {
  await client.callTool({ name: 'query', arguments });
} catch (e) {
  if (e instanceof Error && e.message.includes('Specify an explicit repo')) {
    const repo = await promptUserForRepo(); // or read gitnexus://repos and pick
    return client.callTool({ name: 'query', arguments: { ...arguments, repo } });
  }
  throw e;
}

Prevention

Always include an explicit repo argument when you control the client — it works in every policy mode.
When adding a second repo to an allowlist, set GITNEXUS_MCP_DEFAULT_REPO or update all callers the same day.
On connect, read gitnexus://repos so you can offer a concrete choice instead of failing.

When it happens

Trigger: GITNEXUS_MCP_ALLOWED_REPOS='frontend,backend' (2+ entries) and no GITNEXUS_MCP_DEFAULT_REPO, then calling a tool with no repo in the arguments — e.g. { search_query: 'auth' } only. A single-entry allowlist auto-selects that repo and does not throw.

Common situations: Growing a deployment from one repo to two: the previously optional repo argument becomes mandatory overnight and every cached agent prompt starts failing. Clients that omit repo because 'the server knows its repo' break when a second repo is indexed and allowed.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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