abhigyanpatwari/GitNexus · warning

Failed to enrich cluster ${community.id}:

Error message

Failed to enrich cluster ${community.id}:

What it means

Cluster enrichment asks an injected LLMClient to generate a semantic name/description for each detected code community via llmClient.generate(prompt). If generate() rejects (transport/auth/rate-limit failure), the catch logs 'Failed to enrich cluster ${community.id}' and stores the community's heuristicLabel with empty keywords and description instead. Note that parseEnrichmentResponse already swallows malformed-JSON responses internally, so this warning almost always indicates the LLM API call itself failed, not response parsing.

Source

Thrown at gitnexus/src/core/ingestion/cluster-enricher.ts:133

        name: community.heuristicLabel,
        keywords: [],
        description: '',
      });
      continue;
    }

    try {
      const prompt = buildEnrichmentPrompt(members, community.heuristicLabel);
      const response = await llmClient.generate(prompt);

      // Rough token estimate
      tokensUsed += prompt.length / 4 + response.length / 4;

      const enrichment = parseEnrichmentResponse(response, community.heuristicLabel);
      enrichments.set(community.id, enrichment);
    } catch (error) {
      // On error, fallback to heuristic
      logger.warn({ error }, `Failed to enrich cluster ${community.id}:`);
      enrichments.set(community.id, {
        name: community.heuristicLabel,
        keywords: [],
        description: '',
      });
    }
  }

  return { enrichments, tokensUsed };
};

// ============================================================================
// BATCH ENRICHMENT (more efficient)
// ============================================================================

/**
 * Enrich multiple clusters in a single LLM call (batch mode)
 * More efficient for token usage but requires larger context window

View on GitHub (pinned to aac7515d2a)

Solutions

1. Inspect the logged { error } field — 401/403 means key problem, 429 means rate limit, ECONNREFUSED/ETIMEDOUT means network
2. Verify and fix the LLM credentials/endpoint configuration your LLMClient was built with
3. For 429s, wait out the rate-limit window or reduce the number of clusters before re-running enrichment
4. Accept the automatic fallback — clusters keep their heuristic labels, which is a cosmetic (not structural) quality loss

Example fix

// before
const response = await llmClient.generate(prompt); // rejects mid-analyze -> warn + heuristic fallback

// after: preflight once before the enrichment loop
try {
  await llmClient.generate('Reply with {"ok":true}');
} catch (e) {
  console.error('LLM unreachable - enrichment will use heuristic labels:', e instanceof Error ? e.message : e);
}

// preflight before enrichClusters: prove the LLM endpoint works
await llmClient.generate('Reply with {"ok":true}').catch((e) => {
  throw new Error(`LLM preflight failed - enrichment will degrade: ${e.message}`);
});

try {
  const enrichment = parseEnrichmentResponse(await llmClient.generate(prompt), heuristicLabel);
  enrichments.set(community.id, enrichment);
} catch (error) {
  enrichments.set(community.id, { name: heuristicLabel, keywords: [], description: '' }); // heuristic fallback
}

When it happens

Trigger: llmClient.generate throwing while enriching a community that has at least one member: invalid/expired API key, unreachable model endpoint, 429 rate limiting, request timeout, or exhausted quota.

Common situations: Running analyze with enrichment enabled but the LLM key env vars unset/expired; corporate proxy blocking the model API; free-tier rate limits hit on repos with many clusters; transient provider outages mid-run.

Related errors

• Batch enrichment failed, falling back to heuristics:
• LLM endpoint circuit open: retry in ${Math.ceil(err.retryAft
• LLM API error (${err.response.status} after retries): ${erro
• LLM request timed out after ${formatTimeoutDuration(config.r
• Failed to download embedding model: ${errMsg} ${endpointHi

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