deepset-ai/haystack · error · DeserializationError

Error while unmarshalling serialized pipeline data. This is

Error message

Error while unmarshalling serialized pipeline data. This is usually caused by malformed or invalid syntax in the serialized representation.

What it means

Pipeline.loads() wraps any exception raised by the marshaller's unmarshal() step in a DeserializationError. This means the serialized string (e.g. YAML or JSON produced by dumps) could not be parsed back into a dictionary, typically because the text is malformed or is not a valid representation for the chosen marshaller.

Source

Thrown at haystack/core/pipeline/base.py:352

        :param callbacks:
            Callbacks to invoke during deserialization.
        :param allowed_modules:
            Additional module patterns whose classes may be imported during deserialization.
            By default, only modules under `haystack`, `haystack_integrations`, `haystack_experimental`,
            `builtins`, `typing`, and `collections` are trusted.
        :param unsafe:
            If `True`, bypass the deserialization allowlist entirely. Only use this when you fully
            trust the source of the serialized data — any class in any importable module can be
            instantiated.
        :raises DeserializationError:
            If an error occurs during deserialization.
        :returns:
            A `Pipeline` object.
        """
        try:
            deserialized_data = marshaller.unmarshal(data)
        except Exception as e:
            raise DeserializationError(
                "Error while unmarshalling serialized pipeline data. This is usually "
                "caused by malformed or invalid syntax in the serialized representation."
            ) from e

        return cls.from_dict(deserialized_data, callbacks, allowed_modules=allowed_modules, unsafe=unsafe)

    @classmethod
    @mark_deserialization_internal
    def load(
        cls: type[T],
        fp: TextIO,
        marshaller: Marshaller = DEFAULT_MARSHALLER,
        callbacks: DeserializationCallbacks | None = None,
        *,
        allowed_modules: list[str] | None = None,
        unsafe: bool = False,
    ) -> T:
        """

View on GitHub (pinned to e318778c9b)

Solutions

Validate/parse the string with an external YAML/JSON parser to find the syntax error before loading
Re-export the pipeline with Pipeline.dumps() instead of hand-editing serialized output
Ensure the same marshaller is used for dumps and loads (check Pipeline.dumps(marshaller=...) vs loads(marshaller=...))
Inspect the chained exception (__cause__) for the exact parser error and line

Example fix

// before
pipe = Pipeline.loads(edited_yaml)  # malformed after manual edit
// after
import yaml
yaml.safe_load(edited_yaml)  # locate syntax error first
pipe = Pipeline.loads(original_yaml)

Defensive patterns

Strategy: try-catch

Validate before calling

import yaml
def is_loadable(data: str) -> bool:
    try:
        yaml.safe_load(data)
        return bool(data and data.strip())
    except yaml.YAMLError:
        return False

Type guard

def is_serialized_pipeline(data: object) -> bool:
    return isinstance(data, str) and len(data.strip()) > 0

Try / catch

from haystack.core.errors import DeserializationError
try:
    pipe = Pipeline.loads(data)
except DeserializationError as e:
    logger.error("Bad pipeline data: %s", e.__cause__)
    raise

Prevention

Never hand-edit serialized pipelines; regenerate with dumps()
Keep dump and load marshalling symmetric
Validate YAML/JSON with a linter before loading
Log e.__cause__ to see the underlying parser error

When it happens

Trigger: Calling Pipeline.loads(data) with a truncated, hand-edited, or syntactically invalid YAML/JSON string; calling loads with data serialized in a different format than the marshaller expects; passing bytes instead of str or empty/None data.

Common situations: Strings stored in a database or config file that were later corrupted; users editing exported YAML pipeline definitions by hand and breaking indentation; mixing formats after changing the default marshaller across Haystack versions.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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