spectreconsole/spectre.console · error · InvalidOperationException

Emoji has null hexcode

Error message

Emoji has null hexcode

What it means

Thrown by EmojiModel.ParseAll: an emoji.json element had a valid label but its hexcode property parsed to null. The hexcode is required to build the Unicode escape sequence for the generated code, so a null value aborts parsing.

Source

Thrown at src/Spectre.Console.SourceGenerator/Emojis/EmojiModel.cs:40

/// Parses emoji data from JSON.
/// </summary>
internal static class EmojiParser
{
    /// <summary>
    /// Parses the emoji.json file and returns all emoji models.
    /// Filters out emojis with multiple codepoints (combinators).
    /// </summary>
    public static EquatableArray<EmojiModel> ParseAll(string json)
    {
        var document = JsonDocument.Parse(json);
        var emojis = new List<EmojiModel>();

        foreach (var element in document.RootElement.EnumerateArray())
        {
            var label = element.GetProperty("label").GetString()
                ?? throw new InvalidOperationException("Emoji has null label");
            var hexcode = element.GetProperty("hexcode").GetString()
                ?? throw new InvalidOperationException("Emoji has null hexcode");
            var emoji = element.GetProperty("emoji").GetString()
                ?? throw new InvalidOperationException("Emoji has null emoji");

            // Skip anything that is not a single code point for now
            if (hexcode.Contains("-"))
            {
                continue;
            }

            // Transform hexcode to Unicode escape sequence
            var code = TransformToUnicode(hexcode);

            // If the emoji does not have the Emoji_Presentation=Yes property,
            // then it doesn't have a Variation Selector-16 suffix, and we should add it.
            var codepoint = int.Parse(hexcode, NumberStyles.HexNumber, CultureInfo.InvariantCulture);
            if (!HasEmojiPresentation(codepoint))
            {
                code += "\\uFE0F";

View on GitHub (pinned to 0acc92fada)

Solutions

1. Locate the offending element and restore a valid hexcode string (e.g. "1F600")
2. Restore emoji.json from the Spectre.Console package
3. Validate the JSON before replacing the bundled file

Example fix

// before
{ "label": "grinning face", "hexcode": null, "emoji": "\ud83d\ude00" }
// after
{ "label": "grinning face", "hexcode": "1F600", "emoji": "\ud83d\ude00" }

// Scan emoji.json for null hexcodes before replacing the file
using var doc = JsonDocument.Parse(File.ReadAllText("emoji.json"));
foreach (var e in doc.RootElement.EnumerateArray())
    if (e.GetProperty("hexcode").ValueKind == JsonValueKind.Null)
        Console.Error.WriteLine("emoji has null hexcode");

When it happens

Trigger: An emoji.json element contains "hexcode": null or yields null for the hexcode property.

Common situations: Editing emoji.json and clearing the hexcode; malformed upstream emoji data; schema drift.

Related errors

• Emoji has null label
• Emoji has null emoji
• Color {number} has null name
• Color {number} has null alias
• Failed to read emoji.json at {file.Path}

AI-assisted analysis of spectreconsole/spectre.console@0acc92fada (2026-08-13). Data as JSON: /api/errors/7c13d83821482a6c. Report an issue: GitHub.