D4Vinci/Scrapling · error · RuntimeError

Can't use `adaptive` features while it's disabled globally,

Error message

Can't use `adaptive` features while it's disabled globally, you have to start a new class instance.

What it means

Selector.save() stores an element's unique properties for the adaptive (self-healing) selection system, but adaptive tracking was not enabled. save() only works when the instance was created with adaptive=True (which also sets up the storage backend); otherwise it raises RuntimeError. There is no way to enable it after construction — the message says to start a new instance.

Source

Thrown at scrapling/parser.py:896

    def save(self, element: HtmlElement, identifier: str) -> None:
        """Saves the element's unique properties to the storage for retrieval and relocation later

        :param element: The element itself that we want to save to storage, it can be a ` Selector ` or pure ` HtmlElement `
        :param identifier: This is the identifier that will be used to retrieve the element later from the storage. See
            the docs for more info.
        """
        if self.__adaptive_enabled and self._storage:
            target_element: Any = element
            if isinstance(target_element, self.__class__):
                target_element = target_element._root

            if self._is_text_node(target_element):
                target_element = target_element.getparent()

            self._storage.save(target_element, identifier)
        else:
            raise RuntimeError(
                "Can't use `adaptive` features while it's disabled globally, you have to start a new class instance."
            )

    def retrieve(self, identifier: str) -> Optional[Dict[str, Any]]:
        """Using the identifier, we search the storage and return the unique properties of the element

        :param identifier: This is the identifier that will be used to retrieve the element from the storage. See
            the docs for more info.
        :return: A dictionary of the unique properties
        """
        if self.__adaptive_enabled and self._storage:
            return self._storage.retrieve(identifier)

        raise RuntimeError(
            "Can't use `adaptive` features while it's disabled globally, you have to start a new class instance."
        )

    # Operations on text functions

View on GitHub (pinned to 5d213a2d47)

Solutions

Re-create the parser with adaptive enabled: page = Selector(content, adaptive=True) (Adaptor(content, adaptive=True) in older versions).
Only call save() in code paths where you know the instance is adaptive — check the instance/config flag you passed.
If you never intend to use auto-match, remove the save() call; it serves no purpose on non-adaptive instances.

Example fix

# before
page = Selector(html)
page.css_first('h1').save('title')  # RuntimeError

# after
page = Selector(html, adaptive=True)
page.css_first('h1').save('title')

Defensive patterns

Strategy: validation

Validate before calling

page = Selector(content, adaptive=True)  # required before any save() call
page.css_first('h1').save('title')

Try / catch

try:
    sel.save('title')
except RuntimeError as e:
    if 'adaptive' in str(e):
        logger.warning('adaptive disabled; skipping save')
    else:
        raise

Prevention

Centralize parser construction so adaptive=True is applied everywhere save() is reachable.
Treat save()/retrieve() as APIs that exist only on adaptive instances.

When it happens

Trigger: Calling selector.save(element, identifier) on a Selector/Adaptor created with the default adaptive=False.

Common situations: Copying tutorial code for the auto-match feature without adding adaptive=True to the constructor; calling save() on sub-elements selected from a non-adaptive root.

Related errors

AI-assisted analysis of D4Vinci/Scrapling@5d213a2d47 (2026-08-14). Data as JSON: /api/errors/be8d2f4b2c759e1a. Report an issue: GitHub.