Textualize/rich · error · ValueError

style must not be set when appending Text instance

Error message

style must not be set when appending Text instance

What it means

Text.append() accepts a style= keyword only for str input. When appending a Text instance, all styling must come from the appended Text's own spans and its .style — copying a caller-supplied style on top is ambiguous (it would need to wrap the copied spans), so rich raises ValueError('style must not be set when appending Text instance').

Source

Thrown at rich/text.py:992

            Text: Returns self for chaining.
        """

        if not isinstance(text, (str, Text)):
            raise TypeError("Only str or Text can be appended to Text")

        if len(text):
            if isinstance(text, str):
                sanitized_text = strip_control_codes(text)
                self._text.append(sanitized_text)
                offset = len(self)
                text_length = len(sanitized_text)
                if style:
                    self._spans.append(Span(offset, offset + text_length, style))
                self._length += text_length
            elif isinstance(text, Text):
                _Span = Span
                if style is not None:
                    raise ValueError(
                        "style must not be set when appending Text instance"
                    )
                text_length = self._length
                if text.style:
                    self._spans.append(
                        _Span(text_length, text_length + len(text), text.style)
                    )
                self._text.append(text.plain)
                self._spans.extend(
                    _Span(start + text_length, end + text_length, style)
                    for start, end, style in text._spans.copy()
                )
                self._length += len(text)
        return self

    def append_text(self, text: "Text") -> "Text":
        """Append another Text instance. This method is more performant than Text.append, but
        only works for Text.

View on GitHub (pinned to 9d8f9a372c)

Solutions

1. Drop style= when appending Text: text.append(other_text).
2. Pre-style the appended Text: text.append(Text('x', style='bold')) or other_text.stylize('bold') before appending.
3. In generic helpers, branch: append(text, style=None if isinstance(text, Text) else style) — or normalize your helper's default style to None, not ''.

Example fix

# before
text.append(label, style='')  # ValueError when label is a Text

# after
text.append(label)  # Text carries its own style
# or: text.append(Text(str(label), style='bold')) for str values

from rich.text import Text
text.append(t if isinstance(t, Text) else str(t), style=None if isinstance(t, Text) else style)

from rich.text import Text

def append_call_args(value: object, style):
    """Return (value, style) safe for Text.append."""
    if isinstance(value, Text):
        return value, None
    return str(value), style

When it happens

Trigger: text.append(other_text, style='bold'); also any default-argument bug where style defaults to '' or a Style object instead of None — note the check is 'style is not None', so even style='' (empty string) raises.

Common situations: Generic append(value, style) helpers that pass style through unconditionally; a refactor that changed a str to a Text mid-pipeline while style= stayed; a default style parameter of '' rather than None that only fails on the Text branch.

Related errors

• expected at least one non-None style
• Only str or Text can be appended to Text
• invalid value for align, expected "left", "center", or "righ
• invalid value for vertical, expected "top", "middle", or "bo
• level must be 'head', 'row' or 'foot'

AI-assisted analysis of Textualize/rich@9d8f9a372c (2026-08-15). Data as JSON: /api/errors/661886fdcc95abb8. Report an issue: GitHub.