deepset-ai/haystack · info · ExperimentalWarning

'{cls.name}' is an experimental component and may change

Error message

'{cls.__name__}' is an experimental component and may change or be removed in future releases without prior deprecation notice.

What it means

Haystack marks some components as experimental via the @experimental decorator (haystack/utils/experimental.py). The decorator wraps __init__ in new_init, which emits this ExperimentalWarning on every instantiation, telling you the class's API may change or disappear without any deprecation cycle.

Source

Thrown at haystack/utils/experimental.py:33

    Components decorated with @experimental are subject to breaking changes
    or removal in future releases without prior deprecation notice.

    ## Usage example

        @_experimental
        @component
        class MyComponent:
            ...
    """
    # getattr/setattr are intentional here: direct attribute access (cls.__init__, cls.__init__ = ...)
    # triggers mypy [misc] and [attr-defined] errors because T is an unbound TypeVar.
    # noqa comments suppress ruff B009/B010 which would auto-revert these back to direct access.
    original_init: Any = getattr(cls, "__init__")  # noqa: B009

    @functools.wraps(original_init)
    def new_init(self: Any, *args: Any, **kwargs: Any) -> None:
        warnings.warn(
            f"'{cls.__name__}' is an experimental component and may change or be removed "
            "in future releases without prior deprecation notice. ",
            ExperimentalWarning,
            stacklevel=2,
        )
        original_init(self, *args, **kwargs)

    setattr(cls, "__init__", new_init)  # noqa: B010
    setattr(cls, "__experimental__", True)  # noqa: B010
    return cls


class ExperimentalWarning(UserWarning):
    """Warning emitted when an experimental Haystack component is instantiated."""

View on GitHub (pinned to e318778c9b)

Solutions

Treat the component as unstable: pin the Haystack version (pip install haystack-ai==X.Y.Z) so its API cannot shift under you
Wrap instantiation behind your own adapter/factory so a future API change or removal requires edits in one place only
Silence it deliberately with warnings.filterwarnings('ignore', category=ExperimentalWarning, module='haystack') once you accept the instability risk
Check release notes for the component's graduation to stable, then drop the adapter/warning filters

Example fix

# before
from haystack.components.experimental import ComponentThatAddsTen
comp = ComponentThatAddsTen()  # ExperimentalWarning every time
# after
import warnings
warnings.filterwarnings("ignore", category=ExperimentalWarning, module="haystack")
# and/or isolate behind an adapter:
def make_component(**kwargs):
    from haystack.components.experimental import ComponentThatAddsTen
    return ComponentThatAddsTen(**kwargs)

Defensive patterns

Strategy: try-catch

Validate before calling

import inspect

def is_experimental(cls) -> bool:
    init = getattr(cls, "__init__", None)
    return init is not None and getattr(init, "__wrapped__", None) is not None and \
        any("experimental" in str(a).lower() for a in getattr(init, "__annotations__", {}).values()) or \
        "experimental" in (cls.__doc__ or "").lower()

Try / catch

import warnings

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always", ExperimentalWarning)
    comp = ComponentThatAddsTen()
    if any(issubclass(w.category, ExperimentalWarning) for w in caught):
        # log and pin/adapter around the unstable component
        print("Using experimental component:", comp.__class__.__name__)

Prevention

Pin the Haystack version whenever you depend on experimental components
Wrap experimental components behind your own adapter class or factory function
Filter ExperimentalWarning in production logging once you accept the risk
Track Haystack release notes for graduation or removal of the component

When it happens

Trigger: Instantiating any class decorated with @experimental, e.g. ComponentThatAddsTen() — the warning fires each time __init__ runs, with the concrete class name interpolated into the message.

Common situations: Trying a new Haystack feature (component still under development) in production or CI; noisy test logs from repeated instantiation; upgrading Haystack and finding the experimental component's API changed or was removed.

Related errors

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/2b281c36d3b0f88a. Report an issue: GitHub.