stride3d/stride · error · SyntaxErrorException

While parsing a tag, find an incorrect leading UTF-8 octet.

Error message

While parsing a tag, find an incorrect leading UTF-8 octet.

What it means

Scanner.ScanTagUri decodes URI-escaped octets (%XX) into UTF-8. When an escape's byte should begin a multi-byte UTF-8 sequence, its leading bits must match 0xC0/0xE0/0xF8 masks; a leading octet like 0x80-0xBF or 0xF8+ cannot start a character, so the scanner throws SyntaxErrorException.

Solutions

Fix the tag so its percent-encoded octets form well-formed UTF-8 (encode the Unicode characters, not raw bytes).
Re-encode the tag from the original string with proper UTF-8 percent-encoding (Uri.EscapeDataString).
Remove the invalid escape sequence if the tag content was not intentional.
Catch SyntaxErrorException and show the mark/position in the error message.

Example fix

// before (input.yaml)
tag: !%C3

// after (input.yaml)
tag: !%C3%A9  // decodes to 'é', a complete UTF-8 sequence

Defensive patterns

Strategy: validation

Validate before calling

// C#
// Ensure tag escapes decode as valid UTF-8 before parsing
byte[] bytes = System.Text.RegularExpressions.Regex.Matches(yamlText, "%([0-9A-Fa-f]{2})")
    .Select(m => Convert.ToByte(m.Groups[1].Value, 16)).ToArray();
try { var s = System.Text.Encoding.UTF8.GetString(bytes); _ = s.Length; }
catch (Exception) { throw new FormatException("Tag contains invalid UTF-8 escape sequence."); }

Try / catch

try { deserializer.Deserialize(reader, targetType); }
catch (SyntaxErrorException ex) { throw new YamlConfigException($"Invalid UTF-8 in tag at line {ex.Start.Line}", ex); }

Prevention

Encode Unicode characters (not raw bytes) when building tags: UTF-8 encode, then percent-encode.
Never slice strings byte-wise in the middle of a multi-byte character.
Keep tags ASCII to avoid UTF-8 decoding paths entirely.

When it happens

Trigger: A tag contains a URI escape whose decoded first byte is not a valid UTF-8 leading octet, e.g. '!%80abc' or '!%FF...' — produced by ScanTagUri after ScanUriEscapes.

Common situations: Tags built by double-encoding or manually assembling bytes of invalid UTF-8; binary data pasted into a tag; encoders that percent-encode raw bytes without validating UTF-8 well-formedness.

Related errors

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/edf45b5dd39e3462. Report an issue: GitHub.

Appendix: source

Thrown at sources/core/Stride.Core.Yaml/Scanner.cs:2181

                    throw new SyntaxErrorException(start, mark, "While parsing a tag, did not find URI escaped octet.");
                }

                // Get the octet.

                int octet = (analyzer.AsHex(1) << 4) + analyzer.AsHex(2);

                // If it is the leading octet, determine the length of the UTF-8 sequence.

                if (width == 0)
                {
                    width = (octet & 0x80) == 0x00 ? 1 :
                        (octet & 0xE0) == 0xC0 ? 2 :
                            (octet & 0xF0) == 0xE0 ? 3 :
                                (octet & 0xF8) == 0xF0 ? 4 : 0;

                    if (width == 0)
                    {
                        throw new SyntaxErrorException(start, mark, "While parsing a tag, find an incorrect leading UTF-8 octet.");
                    }
                }
                else
                {
                    // Check if the trailing octet is correct.

                    if ((octet & 0xC0) != 0x80)
                    {
                        throw new SyntaxErrorException(start, mark, "While parsing a tag, find an incorrect trailing UTF-8 octet.");
                    }
                }

                // Copy the octet and move the pointers.

                charBytes.Add((byte) octet);

                Skip();
                Skip();

View on GitHub (pinned to 96fad776d2)