What causes "Unknown resource: ${uri}" in abhigyanpatwari/GitNexus?

Restrict resourceType to context, clusters, processes, schema, cluster/{id}, process/{name}

Unknown resource: ${uri}

Error message

Unknown resource: ${uri}

What it means

Thrown by readResource's dispatch switch: the URI parsed to kind 'repo', but its resourceType (the joined remaining path after the repo name) is not one of the six known values — context, clusters, processes, schema, cluster (with param), process (with param). The default arm rejects everything else.

Source

Thrown at gitnexus/src/mcp/resources.ts:285

  }

  const repoName = parsed.repoName;

  switch (parsed.resourceType) {
    case 'context':
      return getContextResource(backend, repoName);
    case 'clusters':
      return getClustersResource(backend, repoName);
    case 'processes':
      return getProcessesResource(backend, repoName);
    case 'schema':
      return getSchemaResource();
    case 'cluster':
      return getClusterDetailResource(parsed.param!, backend, repoName);
    case 'process':
      return getProcessDetailResource(parsed.param!, backend, repoName);
    default:
      throw new Error(`Unknown resource: ${uri}`);
  }
}

// ─── Resource Implementations ─────────────────────────────────────────

/**
 * Repos resource — list all indexed repositories
 */
async function getReposResource(backend: LocalBackend): Promise<string> {
  const repos = await backend.listRepos();

  if (repos.length === 0) {
    return 'repos: []\n# No repositories indexed. Run: gitnexus analyze';
  }

  const lines: string[] = ['repos:'];
  for (const repo of repos) {
    lines.push(`  - name: "${repo.name}"`);

View on GitHub (pinned to 0d1aed942f)

Solutions

Restrict resourceType to context, clusters, processes, schema, cluster/{id}, process/{name}
Fetch resources/list on connect and only read URIs it advertises
Upgrade the gitnexus package and the client together to remove version skew

Example fix

// before
const uri = `gitnexus://repo/${repoName}/symbols`;

// after
const uri = `gitnexus://repo/${repoName}/schema`;

Defensive patterns

Strategy: validation

Validate before calling

const REPO_RESOURCE_TYPES = ['context', 'clusters', 'processes', 'schema'];
function isKnownRepoResourceType(t) {
  return REPO_RESOURCE_TYPES.includes(t) || t.startsWith('cluster/') || t.startsWith('process/');
}

Type guard

function parseRepoUriSafe(uri) {
  try {
    const u = new URL(uri);
    if (u.protocol !== 'gitnexus:' || u.hostname !== 'repo') return null;
    const seg = u.pathname.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
    if (seg.length < 2) return null;
    return { repoName: seg[0], resourceType: seg.slice(1).join('/') };
  } catch { return null; }
}

Try / catch

try { return await readResource(uri, backend); }
catch (e) {
  if (e.message === `Unknown resource: ${uri}`) return fallbackToSchemaResource(); // degrade to a known-good resource
  throw e;
}

Prevention

Filter candidate URIs through isKnownRepoResourceType before reading
On MCP client startup, read resources/list and derive the allowed URI set from it
Log the exact URI with the failure so hallucinated names are visible in traces

When it happens

Trigger: resources/read with 'gitnexus://repo/{name}/symbols', 'gitnexus://repo/{name}/wiki', or any second segment outside the known set; also a version-skew case where a client requests a resource type that the running GitNexus version does not implement.

Common situations: An LLM MCP client hallucinating plausible-sounding resource names; clients written against an older/newer GitNexus whose resource set differs; copying a URI from documentation for a different edition.

Related errors

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