langflow-ai/langflow · error · ImportError

Cannot import for backwards compatibility with

Error message

Cannot import {self._lfx_module_name} for backwards compatibility with {self.__name__}

What it means

The langflow package uses a lazy shim module (a ModuleType subclass in src/backend/base/langflow/__init__.py) that forwards attribute access to the corresponding lfx module for backwards compatibility. On first attribute access it imports the lfx module; if that import fails, the original ImportError is chained into a new ImportError naming the missing lfx module and the shim being accessed. Hitting it means the lfx package is not installed, not on sys.path, or itself fails to import.

Solutions

Sync the full workspace: 'uv sync' from the repo root so lfx is installed alongside langflow-base.
Verify the shim target resolves: 'uv run python -c "import lfx; print(lfx.__file__)"'.
If lfx imports but an inner module fails, debug that ImportError in lfx directly — the chained exception ('from e') shows the root cause.
Pin matching versions: never mix an old langflow-base with a newer lfx (or vice versa) from different releases.

Example fix

# before: langflow-base installed alone, then
import langflow  # ok
langflow.ChatInput  # ImportError: Cannot import lfx... for backwards compatibility
# after: install the whole workspace
# uv sync
import langflow
langflow.ChatInput  # forwards to lfx module

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util
if importlib.util.find_spec("lfx") is None:
    raise SystemExit("lfx not installed — run 'uv sync' at the repo root")

Try / catch

import langflow
try:
    ChatInput = langflow.ChatInput
except ImportError as e:
    if "backwards compatibility" in str(e):
        raise SystemExit("lfx package missing/broken — run 'uv sync' and retry") from e
    raise

Prevention

Use 'uv sync' at the repo root instead of installing langflow-base alone.
Smoke-test 'import langflow; langflow.ChatInput' after environment changes.
Keep langflow-base and lfx versions from the same release.

When it happens

Trigger: Any 'from langflow import X' or 'langflow.X' where X is not defined in the legacy package and the lazy shim must import lfx.<something>; running against an environment where the lfx workspace member is not installed (e.g. only langflow-base installed); a broken lfx install or an import error inside lfx itself.

Common situations: Installing langflow-base alone without the lfx package; partial 'uv sync' that resolved only the top-level workspace; version mismatch after the langflow->lfx code move; a transitive import error inside lfx surfacing through the shim.

Related errors

AI-assisted analysis of langflow-ai/langflow@976ec789d2 (2026-08-14). Data as JSON: /api/errors/c2a19a3d5f04686f. Report an issue: GitHub.

Appendix: source

Thrown at src/backend/base/langflow/__init__.py:131

        )


class LangflowCompatibilityModule(ModuleType):
    """A module that forwards attribute access to the corresponding lfx module."""

    def __init__(self, name: str, lfx_module_name: str):
        super().__init__(name)
        self._lfx_module_name = lfx_module_name
        self._lfx_module = None

    def _get_lfx_module(self):
        """Lazily import and cache the lfx module."""
        if self._lfx_module is None:
            try:
                self._lfx_module = importlib.import_module(self._lfx_module_name)
            except ImportError as e:
                msg = f"Cannot import {self._lfx_module_name} for backwards compatibility with {self.__name__}"
                raise ImportError(msg) from e
        return self._lfx_module

    def __getattr__(self, name: str) -> Any:
        """Forward attribute access to the lfx module with caching."""
        lfx_module = self._get_lfx_module()
        try:
            attr = getattr(lfx_module, name)
        except AttributeError as e:
            msg = f"module '{self.__name__}' has no attribute '{name}'"
            raise AttributeError(msg) from e
        else:
            # Cache the attribute in our __dict__ for faster subsequent access
            setattr(self, name, attr)
            return attr

    def __dir__(self):
        """Return directory of the lfx module."""
        try:

View on GitHub (pinned to 976ec789d2)