reflex-dev/reflex · error · TypeError

f"Expected EscapeSequence to have a single RawText child, go

Error message

f"Expected EscapeSequence to have a single RawText child, got {children!r}"

What it means

Similar to InlineCode, the docgen parser expects EscapeSequence tokens (backslash escapes) to wrap exactly one RawText child. Any deviation raises TypeError, and it is the final guard before the generic 'Unsupported span token type' error — so it fires only on structurally unexpected escapes, typically after a parser library upgrade.

Source

Thrown at packages/reflex-docgen/src/reflex_docgen/markdown/_parser.py:182

    if isinstance(token, Link):
        return LinkSpan(children=_convert_children(token), target=token.target)

    if isinstance(token, Image):
        return ImageSpan(children=_convert_children(token), src=token.src)

    if isinstance(token, LineBreak):
        return LineBreakSpan(soft=token.soft)

    if isinstance(token, EscapeSequence):
        # EscapeSequence.children is a tuple of one RawText with the escaped char.
        children = token.children
        if (
            not isinstance(children, tuple)
            or len(children) != 1
            or not isinstance(children[0], RawText)
        ):
            msg = f"Expected EscapeSequence to have a single RawText child, got {children!r}"
            raise TypeError(msg)
        return TextSpan(text=children[0].content)

    msg = f"Unsupported span token type: {type(token).__name__}"
    raise TypeError(msg)


def _convert_children(token: object) -> tuple[Span, ...]:
    """Convert the children of a mistletoe token into Spans.

    Args:
        token: A mistletoe token with a children attribute.

    Returns:
        A tuple of Span objects.
    """
    children = getattr(token, "children", None)
    if children is None:
        return ()

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Rewrite the escaped markdown to avoid the edge case (e.g. use a code span instead of backslash escapes: `a\*b`)
2. Restore the locked parser version: git checkout uv.lock && uv sync
3. Report upstream with the minimal markdown that triggers it

Example fix

# before
# doc line: cost is 5\*3 dollars
# after
# doc line: cost is `5*3` dollars

try:
    doc = parse_markdown(md_text)
except TypeError as e:
    logger.warning('escape sequence parse failed for %s: %s', path, e)
    doc = parse_markdown(md_text.replace('\\', ''))

When it happens

Trigger: Parsing markdown with escape sequences (\*, \_) whose token tree has no single RawText child; version drift between mistletoe and reflex-docgen's expected AST shape.

Common situations: CI docgen after dependency refresh; docs containing heavy backslash escaping (regex examples, LaTeX-ish text).

Related errors

• Markdown component must have exactly one child containing th
• f"No markdown component found for tag: {tag}."
• ChildrenTypeError(component=cls.__name__, child=child)
• Do not override _add_style directly. Use add_style instead.
• The component `{comp_name}` cannot have `{child_name}` as a

AI-assisted analysis of reflex-dev/reflex@45b8ed5ab7 (2026-08-28). Data as JSON: /api/errors/2d1894999c6cae25. Report an issue: GitHub.