langflow-ai/langflow · error · HTTPException

Error loading flow module: {e}

Error message

Error loading flow module: {e}

What it means

Raised when spec.loader.exec_module(module) throws while executing the .py flow file — i.e. the file loaded but running its top-level code failed (syntax error at exec time, ImportError of a missing dependency, exception at module level). The module entry is cleaned out of sys.modules, the exception is logged ('Error loading flow module: {e}'), and HTTP 500 with the exception text is returned.

Source

Thrown at src/backend/base/langflow/agentic/services/helpers/flow_loader.py:149

    Raises:
        HTTPException: If the flow file cannot be loaded or executed.
    """
    module_name = flow_path.stem
    spec = importlib.util.spec_from_file_location(module_name, flow_path)
    if spec is None or spec.loader is None:
        raise HTTPException(status_code=500, detail=f"Could not load flow module: {flow_path}")

    module = importlib.util.module_from_spec(spec)
    sys.modules[module_name] = module

    try:
        with _temporary_sys_path(str(flow_path.parent)):
            spec.loader.exec_module(module)
    except Exception as e:
        if module_name in sys.modules:
            del sys.modules[module_name]
        logger.error(f"Error loading Python flow module: {e}")
        raise HTTPException(status_code=500, detail=f"Error loading flow module: {e}") from e

    if not hasattr(module, "get_graph"):
        # Fallback: check for 'graph' variable for backward compatibility
        if hasattr(module, "graph"):
            graph = module.graph
            validate_flow_for_current_settings(graph)
            if module_name in sys.modules:
                del sys.modules[module_name]
            return graph
        if module_name in sys.modules:
            del sys.modules[module_name]
        raise HTTPException(status_code=500, detail=f"Flow module must define 'get_graph()' function: {flow_path}")

    get_graph_func = module.get_graph

    # Build kwargs for get_graph based on what it accepts
    sig = inspect.signature(get_graph_func)
    kwargs = {}

View on GitHub (pinned to 976ec789d2)

Solutions

1. Read the 500 detail — it contains the actual exception (e.g. ModuleNotFoundError: No module named 'x') — and fix that import or add the dependency to the server environment.
2. Move environment-dependent logic inside get_graph() instead of module top-level so loading never depends on runtime state.
3. Run 'python <flow>.py' in the server environment locally to reproduce the exec failure quickly.
4. Keep the flow file dependency-free except for langflow/lfx APIs where possible.

Example fix

# before (module-level, breaks load if var missing)
import os
KEY = os.environ['MY_KEY']
def get_graph(): ...
# after (lazy, load always succeeds)
import os
def get_graph():
    key = os.environ.get('MY_KEY', '')
    ...

subprocess.run(['python', '-m', 'py_compile', str(flow_path)], check=True)  # catches syntax errors pre-deploy
# plus: import the module in a throwaway venv matching the server env to catch ImportErrors

except HTTPException as e:
    if e.status_code == 500 and 'Error loading flow module' in e.detail:
        show_author_error(e.detail)  # contains the real exception, e.g. ModuleNotFoundError
        block_deployment()

When it happens

Trigger: A Python flow file that imports a package not installed in the server environment, raises at import time (e.g. reads a missing env var at module scope), or contains a SyntaxError that only surfaces on execution; the file's parent dir is temporarily added to sys.path during exec, so relative imports of sibling modules can also fail.

Common situations: Flow depends on a library (requests, langchain community packages, etc.) missing from the server venv; module-level code assuming environment variables or files; flow developed against a different Langflow version whose APIs moved; syntax valid for a newer Python than the server runs.

Related errors

• Could not load flow module: {flow_path}
• Could not import {attr_name!r} from {__name__!r}: {e}
• An error occurred while executing the flow.
• An internal error occurred while executing the flow.
• An error occurred while preparing the flow.

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