microsoft / microsoft/graphrag

[Bug]: use_lcc silently drops case-sensitive entity titles from every community

Open
#2,427 1 comment 0 reactions 1 assignee View on GitHub

@natoverse is already working on this.

Since Jul 8, 2026.

backlog
Dominant language
Python
Stars
36k
Forks
3.8k
Avg merge
20h 40m
Merged PRs (30d)
4

Description

Do you need to file an issue?
  • I have searched the existing issues and this bug is not already filed.
  • My model is hosted on OpenAI or Azure. (N/A — reproduces independent of model provider; this is a pure data-pipeline bug, not an LLM output issue)
  • I believe this is a legitimate bug, not just a question.
Describe the bug

When bringing your own graph (BYOG) with cluster_graph.use_lcc: true (the default), entities whose title contains lowercase characters are silently dropped from every community — with no warning, error, or log line. create_communities reports success and writes N communities, but coverage across all communities can be far less than the number of input entities.

Root cause: graphs/stable_lcc.py's normalize_node_name does html.unescape(name).upper().strip() before computing the largest connected component, and this uppercased form is what gets passed into hierarchical_leiden — so the cluster labels that come back out of cluster_graph() are uppercase. index/workflows/create_communities.py's create_communities() then joins those cluster labels back against entities.title via exact case-sensitive string matching (title_to_entity_id dict lookup, and relationships.merge(level_comms, left_on="source", right_on="title")). Any title that wasn't already all-uppercase fails to match: entity_map["entity_id"] comes back NaN and is dropped via .dropna(), and any community with no matched intra-community edges is dropped entirely by the final inner merge against entity_ids.

This is presumably fine for GraphRAG's own LLM-extraction pipeline, where entity names are conventionally emitted uppercase already — but it's a silent correctness bug for BYOG users bringing case-sensitive titles (e.g. a codebase's real identifier names, which is a very natural BYOG use case).

Steps to reproduce
  1. Build a minimal BYOG entities.parquet / relationships.parquet per the BYOG guide with at least one entity title containing lowercase letters (e.g. FooBar, BazQux), and a relationship between two such entities.
  2. Configure workflows: [create_communities, create_community_reports] with default cluster_graph.use_lcc: true.
  3. Run graphrag index.
  4. Inspect output/communities.parquet — the mixed-case entities never appear in any community's entity_ids, despite being connected in relationships.parquet.
Expected Behavior

Every entity that appears in a connected relationship should be assigned to some community, or the pipeline should surface a warning when input entities can't be matched back after LCC normalization.

GraphRAG Config Used
cluster_graph:
  max_cluster_size: 10
  use_lcc: true  # default - triggers the bug
workflows: [create_communities, create_community_reports, generate_text_embeddings]
Logs and screenshots

N/A — the bug produces no error output; it is a silent data-loss issue only visible by comparing entity counts in entities.parquet against total entity_ids coverage across communities.parquet.

Additional Information
  • GraphRAG Version: 3.1.0
  • Operating System: macOS 26.5.1
  • Python Version: 3.12.13
  • Related Issues: none found

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.