abhigyanpatwari/GitNexus · error

Unknown tool: ${method}

Error message

Unknown tool: ${method}

What it means

LocalBackend's tool dispatch switch (overview, route_map, shape_check, tool_map, api_impact, trace, ...) fell through to default: the method string does not name any tool this backend implements. It is a pure name mismatch — the request reached the right backend but asked for an unknown capability.

Source

Thrown at gitnexus/src/mcp/local/local-backend.ts:2551

      case 'explore':
        return this.context(repo, {
          name: typeof p.name === 'string' ? p.name : undefined,
          ...p,
        });
      case 'overview':
        return this.overview(repo, p);
      case 'route_map':
        return this.routeMap(repo, p);
      case 'shape_check':
        return this.shapeCheck(repo, p);
      case 'tool_map':
        return this.toolMap(repo, p);
      case 'api_impact':
        return this.apiImpact(repo, p);
      case 'trace':
        return this.trace(repo, p);
      default:
        throw new Error(`Unknown tool: ${method}`);
    }
  }

  // ─── Tool Implementations ────────────────────────────────────────

  /** Check repository graph invariants that are suitable for CI gating. */
  private async check(repo: RepoHandle, params?: { cycles?: boolean }): Promise<any> {
    if (params?.cycles === false) {
      return { error: 'No checks selected. Set "cycles" to true.' };
    }
    await this.ensureInitialized(repo);
    const rowLimit = 100_001;
    // determinism: probe — overflow guard, not a window. The one-past cap is compared for exact equality below
    // and the whole result is REPLACED by an error, so a truncated page never reaches a caller.
    const rows = await executeParameterized(
      repo.lbugPath,
      // A cycle here means "these modules cannot be initialized in any order".
      // Only edges that force initialization count, so four kinds are excluded:

View on GitHub (pinned to 0d1aed942f)

Solutions

1. List the tools the backend actually serves (MCP tools/list, or the GitNexus MCP docs for your installed version) and correct the name.
2. Update gitnexus (`npm update -g gitnexus`) if the docs you followed are newer than your install.
3. Check for renames: removed group_query/group_contracts/group_status must be expressed as repo "@<groupName>" on impact/query/context or via MCP resources.
4. Fix typos in hand-rolled client code that builds method strings dynamically.

Example fix

// before: unknown/renamed method
await backend.callTool('route-map', { repo: 'myrepo' });   // hyphen vs underscore

// after: exact tool name from tools/list
await backend.callTool('route_map', { repo: 'myrepo' });
// removed group tools → new form:
await callTool('query', { search_query: 'x', repo: '@mygroup' });

// Fetch the server's real tool list and validate before dispatch
const { tools } = await client.listTools();
const known = new Set(tools.map((t: { name: string }) => t.name));

function assertKnownTool(method: string): void {
  if (!known.has(method)) {
    throw new Error(`Unknown tool "${method}". Available: ${[...known].sort().join(', ')}`);
  }
}

const isKnownTool = (method: string, available: ReadonlySet<string>): method is string =>
  available.has(method); // compile-time narrow via a branded tool-name type if you generate one

try {
  return await backend.callTool(method, params);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Unknown tool:')) {
    // reconcile against tools/list; surface available names instead of retrying blindly
    const available = (await client.listTools()).tools.map((t: any) => t.name).join(', ');
    throw new Error(`${err.message}. Server offers: ${available}`);
  }
  throw err;
}

When it happens

Trigger: An MCP client calling a tool name the installed GitNexus version does not implement: typos, tools renamed or not yet shipped in that version, or stale client configs written against different GitNexus docs. Also direct backend calls in tests with a wrong method string.

Common situations: Version skew between the MCP client config (or AI-agent instructions) and the installed gitnexus package; agents hallucinating tool names; tool families that moved namespaces (e.g. group_* tools folded into the repo parameter, cf. the group-tool variant); copy-pasted examples from newer docs on older installs.

Related errors

• Tool "${toolName}" is not available in GitNexus MCP read-onl
• Unknown group tool: ${method}. Removed tools: use repo "@<gr
• Missing Content-Length header from MCP client
• Invalid Content-Length header from MCP client
• Content-Length ${contentLength} exceeds maximum allowed size

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