pathwaycom/pathway · error · ImportError

LEANN connector requires the `leann` package. Please visit h

Error message

LEANN connector requires the `leann` package. Please visit https://github.com/yichuan-w/LEANN and follow the installation instructions there.

What it means

The LEANN sink builds a vector index at the end of the pipeline, which requires the third-party `leann` Python package. When the import inside _build_index() fails, Pathway re-raises a helpful ImportError pointing at the LEANN project's install instructions. The error surfaces lazily — at index build time (on_flush/on_end), not at write() call time.

Source

Thrown at python/pathway/io/leann/__init__.py:91

            self._dirty = True
        else:
            if self.documents.pop(key, None) is not None:
                self._dirty = True

    def on_time_end(self, time: int) -> None:
        if self._dirty:
            self._build_index()
            self._dirty = False

    def on_end(self) -> None:
        if self._dirty or not self.index_path.exists():
            self._build_index()

    def _build_index(self) -> None:
        try:
            from leann import LeannBuilder
        except ImportError as e:
            raise ImportError(_LEANN_INSTALL_ERROR_MESSAGE) from e

        if not self.documents:
            logger.warning("No documents to index - skipping index build")
            return

        builder_kwargs: dict[str, Any] = {"backend_name": self.backend_name}
        if self.embedding_mode:
            builder_kwargs["embedding_mode"] = self.embedding_mode
        if self.embedding_model:
            builder_kwargs["embedding_model"] = self.embedding_model
        if self.embedding_options:
            builder_kwargs["embedding_options"] = self.embedding_options

        builder = LeannBuilder(**builder_kwargs)
        for doc in self.documents.values():
            builder.add_text(**doc)

        # Ensure parent directory exists

View on GitHub (pinned to fa2f74a464)

Solutions

Install the leann package following https://github.com/yichuan-w/LEANN instructions (e.g. pip install leann)
Verify with `python -c "import leann"` before running the pipeline
Prefer the eager check by relying on pw.io.leann.write's own _check_leann_available() — call pw.io.leann.write early so the ImportError triggers at graph-build time rather than mid-run

Example fix

# before: pipeline fails at index build
pw.io.leann.write(table, "idx", table.text)

# after: fail fast in setup
import leann  # ImportError surfaces immediately if missing
pw.io.leann.write(table, "idx", table.text)

Defensive patterns

Strategy: validation

Validate before calling

try:
    import leann  # noqa
except ImportError:
    raise SystemExit("Install leann first: see https://github.com/yichuan-w/LEANN")

Try / catch

try:
    pw.io.leann.write(table, "idx", table.text)
except ImportError as e:
    print("Missing dependency:", e)
    raise

Prevention

Declare leann in your project's dependency list so environments always have it
Import leann at application startup to surface missing installs immediately
Pin a leann version to avoid breaking upstream API changes

When it happens

Trigger: Calling pw.io.leann.write(...) in an environment where `import leann` fails; because _build_index runs in an observer callback, the pipeline may run for a while before the ImportError appears.

Common situations: Missing optional dependency (leann is not bundled with pathway); partially installed leann without its native backend; CI image that installs pathway but not the extra.

Related errors

AI-assisted analysis of pathwaycom/pathway@fa2f74a464 (2026-08-15). Data as JSON: /api/errors/f54f6894369aaed6. Report an issue: GitHub.