stride3d/stride · error · SyntaxErrorException

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

Error message

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

What it means

While decoding a multi-byte UTF-8 character in a tag URI (Scanner.ScanTagUri), a continuation octet must have the form 10xxxxxx ((octet & 0xC0) == 0x80). If an escaped octet in the middle of a sequence does not, the sequence is malformed and the scanner throws SyntaxErrorException.

Solutions

Repair the escape sequence so all continuation bytes are 0x80-0xBF (e.g. complete %C3%A9).
Regenerate the tag encoding by re-encoding the intended Unicode string as UTF-8 then percent-encoding.
Shorten the tag to end at a character boundary if the tail is corrupt.
Catch SyntaxErrorException and report the exact mark for debugging the input.

Example fix

// before (input.yaml)
label: !%C3%28

// after (input.yaml)
label: !%C3%A9

Defensive patterns

Strategy: validation

Try / catch

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

Prevention

Re-encode tags from a managed string with Uri.EscapeDataString so sequences are always complete.
Validate files after any byte-level transformation (FTP ASCII mode, old editors, encodings).
Use ASCII-only tag names in configuration you control.

When it happens

Trigger: A tag's %XX escape sequence declares a multi-byte character (e.g. starts with %E0 or %C3) but a following octet is not a continuation byte, e.g. '!%C3%4G' or '!%E0%A0' with a bad third byte.

Common situations: Truncated or hand-assembled percent escapes; byte-level string manipulation (substring in the middle of a character); data corrupted when passing through a non-UTF-8-safe channel.

Related errors

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

Appendix: source

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

                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();
                Skip();
            } while (--width > 0);

            char[] characters = Encoding.UTF8.GetChars(charBytes.ToArray());

            if (characters.Length != 1)
            {
                throw new SyntaxErrorException(start, mark, "While parsing a tag, find an incorrect UTF-8 sequence.");
            }

View on GitHub (pinned to 96fad776d2)