dotnet/wpf · error · ArgumentException

SR.ClusterMapEntryShouldPointWithinGlyphIndices

Error message

SR.ClusterMapEntryShouldPointWithinGlyphIndices

What it means

GlyphRun.Initialize requires every clusterMap entry to point to a valid glyph index position: clusterMap[i] must be < GlyphCount. An entry at or beyond the glyph count has no corresponding glyph, so the run is invalid. It throws ArgumentException naming the clusterMap parameter.

Solutions

  1. Clamp or rebuild clusterMap so every entry is < GlyphCount
  2. Recompute the cluster map after any change to glyphIndices
  3. Validate with clusterMap.All(v => v < glyphIndices.Count) before calling the API

Example fix

// before
int[] clusterMap = { 0, 5 }; // glyphs.Count == 3
// after
int[] clusterMap = { 0, 2 }; // entries within [0, GlyphCount)
Defensive patterns

Strategy: validation

Validate before calling

if (clusterMap != null && clusterMap.Any(v => v < 0 || v >= glyphIndices.Count))
    throw new ArgumentException("clusterMap entry out of glyph range");

Type guard

static bool EntriesWithinGlyphs(int[] map, int glyphCount) => map == null || map.All(v => v >= 0 && v < glyphCount);

Try / catch

try { var run = new GlyphRun(...); }
catch (ArgumentException ex) when (ex.ParamName == "clusterMap") { /* regenerate map */ }

Prevention

When it happens

Trigger: Constructing a GlyphRun (constructor, TryCreate, or EndInit) where clusterMap contains a value >= glyphIndices.Count, typically after shrinking glyphIndices without updating the cluster map.

Common situations: Trimming glyphs from a run but leaving the original cluster map; building clusterMap with 1-based or character-count-based indices while expecting glyph-index semantics.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of dotnet/wpf@81131a70a4 (2026-09-14). Data as JSON: /api/errors/3d8ff5b6e0412972. Report an issue: GitHub.

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationCore/System/Windows/Media/GlyphRun.cs:387

                            {
                                int glyphCount = GlyphCount;
                                int mapCount = clusterMap.Count;
                                ushort previous = clusterMap[0];

                                for (int i = 1; i < mapCount; ++i)
                                {
                                    ushort current = clusterMap[i];
                                    if ((current >= previous) && (current < glyphCount))
                                    {
                                        previous = current;
                                    }
                                    else
                                    {
                                        if (clusterMap[i] < clusterMap[i - 1])
                                            throw new ArgumentException(SR.ClusterMapEntriesShouldNotDecrease, nameof(clusterMap));

                                        if (clusterMap[i] >= GlyphCount)
                                            throw new ArgumentException(SR.ClusterMapEntryShouldPointWithinGlyphIndices, nameof(clusterMap));
                                    }
                                }
                            }
                            else
                            {
                                throw new ArgumentException(SR.ClusterMapFirstEntryMustBeZero, nameof(clusterMap));
                            }
                        }
                        else
                        {
                            throw new ArgumentException(SR.Format(SR.CollectionNumberOfElementsShouldBeEqualTo, characters.Count), nameof(clusterMap));
                        }
                    }
                    else
                    {
                        if (GlyphCount != characters.Count)
                            throw new ArgumentException(SR.Format(SR.CollectionNumberOfElementsShouldBeEqualTo, GlyphCount), nameof(clusterMap));
                    }

View on GitHub (pinned to 81131a70a4)