deepset-ai/haystack · error · PipelineError

Component '{component_type}' (name: '{name}') not imported.

Error message

Component '{component_type}' (name: '{name}') not imported. Please check that the package is installed and the component path is correct.

What it means

The fallback wrapper around component import failures during from_dict: if importing the component's module raises ImportError, PipelineError, or ValueError, Haystack raises this PipelineError indicating the component could not be imported at all. It points at a missing package or an incorrect component path in the serialized pipeline.

Source

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

                if isinstance(component_type, str) and "." in component_type:
                    _check_module_allowed(component_type.rsplit(".", 1)[0])

                if component_type not in component.registry:
                    try:
                        # Import the module first...
                        module, _ = component_type.rsplit(".", 1)
                        logger.debug("Trying to import module {module_name}", module_name=module)
                        type_serialization.thread_safe_import(module)
                        # ...then try again
                        if component_type not in component.registry:
                            raise PipelineError(  # noqa: TRY301
                                f"Successfully imported module '{module}' but couldn't find "
                                f"'{component_type}' in the component registry.\n"
                                f"The component might be registered under a different path. "
                                f"Here are the registered components:\n {list(component.registry.keys())}\n"
                            )
                    except (ImportError, PipelineError, ValueError) as e:
                        raise PipelineError(
                            f"Component '{component_type}' (name: '{name}') not imported. Please "
                            f"check that the package is installed and the component path is correct."
                        ) from e

                # Create a new one
                component_class = component.registry[component_type]

                try:
                    instance = component_from_dict(component_class, component_data, name, callbacks)
                except Exception as e:
                    # Convert to JSON with indentation, truncate if too long
                    try:
                        data_str = json.dumps(component_data, default=str, indent=2)
                    except Exception:
                        data_str = str(component_data)

                    max_len = 1000
                    if len(data_str) > max_len:

View on GitHub (pinned to e318778c9b)

Solutions

pip install the package that provides the component (e.g. haystack-ai extras or integration packages)
Correct the module path in the pipeline 'type' string
Verify with python -c "import <module>" that the module imports in the target environment
Align haystack package versions between the environment that dumped and the one that loads the pipeline

Example fix

// before
# yaml uses type: haystack.components.retrievers.inmemory.MyRetriever (doesn't exist)

// after
# pip install the integration or fix path:
type: haystack.components.retrievers.in_memory.InMemoryEmbeddingRetriever

Defensive patterns

Strategy: validation

Validate before calling

def check_component_imports(data: dict) -> list[str]:
    errors = []
    for comp in data.get("components", {}).values():
        t = comp.get("type", "")
        if isinstance(t, str) and "." in t:
            module = t.rsplit(".", 1)[0]
            try:
                __import__(module)
            except ImportError as e:
                errors.append(f"{t}: {e}")
    return errors

Type guard

def component_importable(component_type: str) -> bool:
    try:
        __import__(component_type.rsplit(".", 1)[0])
        return True
    except ImportError:
        return False

Try / catch

try:
    pipe = Pipeline.from_dict(data)
except PipelineError as e:
    if "not imported" in str(e):
        logging.error("Install the missing package or fix the path: %s", e)
        raise

Prevention

pip install every integration package the pipeline references
Load pipelines in the same environment (and versions) they were dumped in
Test-serialize and reload pipelines in CI
Validate module paths with python -c "import ..." before deployment

When it happens

Trigger: from_dict encountering a 'type' whose module doesn't exist (typo in module path), whose package isn't installed (e.g. an integration like haystack.components.extractors requiring uninstalled extras), or which raises ValueError during import.

Common situations: Using a pipeline YAML with integration components without pip installing the integration package; typos in the module path; version mismatch where a component moved to a new module; importing a pipeline in a different environment than it was created in.

Related errors

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