reflex-dev/reflex · error · NotImplementedError

LiteralVar subclasses must implement the json method.

Error message

LiteralVar subclasses must implement the json method.

What it means

LiteralVar's base class declares json() as an abstract-ish method: it must serialize the var to a JSON string for embedding in the frontend. A subclass that does not override json() triggers this NotImplementedError when any code path serializes the var (e.g. during component compilation or state hydration). It is an internal contract for Var subclass authors, not end-user code.

Source

Thrown at packages/reflex-base/src/reflex_base/vars/base.py:1820

        if isinstance(value, range):
            return None

        msg = f"Unsupported type {type(value)} for LiteralVar. Tried to create a LiteralVar from {value}."
        raise TypeError(msg)

    @property
    def _var_value(self) -> Any:
        msg = "LiteralVar subclasses must implement the _var_value property."
        raise NotImplementedError(msg)

    def json(self) -> str:
        """Serialize the var to a JSON string.

        Raises:
            NotImplementedError: If the method is not implemented.
        """
        msg = "LiteralVar subclasses must implement the json method."
        raise NotImplementedError(msg)


@serializers.serializer
def serialize_literal(value: LiteralVar):
    """Serialize a Literal type.

    Args:
        value: The Literal to serialize.

    Returns:
        The serialized Literal.
    """
    return value._var_value


def get_python_literal(value: LiteralVar | Any) -> Any | None:
    """Get the Python literal value.

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Implement def json(self) -> str in your LiteralVar subclass returning json.dumps(self._var_value)
2. Prefer returning a built-in literal type (str/int/bool/list/dict) from serializers so Reflex wraps it in a standard LiteralVar subclass
3. If no custom subclass exists in your project, run uv sync to realign workspace package versions

Example fix

# before
class MyLiteralVar(rx.vars.LiteralVar):
    ...

# after
import json
class MyLiteralVar(rx.vars.LiteralVar):
    @property
    def _var_value(self):
        return self.value

    def json(self) -> str:
        return json.dumps(self.value)

from reflex.vars.base import LiteralVar

def implements_json(v: LiteralVar) -> bool:
    return type(v).json is not LiteralVar.json

try:
    s = lit.json()
except NotImplementedError:
    s = repr(lit._var_value)  # degrade gracefully; fix the subclass

When it happens

Trigger: Creating a custom LiteralVar subclass without a json() method and then compiling the app or otherwise serializing it; calling var.json() directly on a LiteralVar that lacks the override.

Common situations: Authoring custom Var types for serializer integrations and forgetting json(); copy-pasting an old LiteralVar subclass across Reflex major versions where the abstract surface grew; version mismatch between reflex and reflex-base packages.

Related errors

• LiteralVar subclasses must implement the _var_value property
• Unexpected keyword arguments: {unexpected_kwargs}
• CallableEventSpec has no associated function.
• Expected _js_expr to be a string, got value {self._js_expr!r
• No valid JSON representation for {self}

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