Graphify-Labs/graphify · error · ImportError

the 'openai' package is required for this backend but is not

Error message

the 'openai' package is required for this backend but is not installed. Install it with:  uv tool install "graphifyy[openai]" --force  (uv tool), or  pip install openai  (pip/venv install).

What it means

ImportError raised for every OpenAI-compatible backend (openai, gemini, kimi, ollama via /v1) when the 'openai' package is not installed. This is the fallback branch of the backend dispatch in llm.py:2706-2709 - anything not claude/claude-cli/bedrock/azure lands here, so the error also fires when a backend name is misspelled into the default path.

Source

Thrown at graphify/llm.py:2709

            "messages": [{"role": "user", "content": prompt}],
            "max_completion_tokens": max_tokens,
        }
        azure_temp = _resolve_temperature(cfg.get("temperature", 0), mdl)
        if azure_temp is not None:
            azure_kwargs["temperature"] = azure_temp
        resp = azure_client.chat.completions.create(**azure_kwargs)
        if not resp.choices or resp.choices[0].message is None:
            raise ValueError("Azure OpenAI returned empty or filtered response")
        au = getattr(resp, "usage", None)
        if au is not None:
            _rec(getattr(au, "prompt_tokens", 0), getattr(au, "completion_tokens", 0))
        return resp.choices[0].message.content or ""

    # OpenAI-compatible (kimi, openai, gemini, ollama)
    try:
        from openai import OpenAI
    except ImportError as exc:
        raise ImportError(_backend_pkg_hint("openai", "openai")) from exc
    client = OpenAI(api_key=key, base_url=cfg["base_url"], timeout=_resolve_api_timeout(), max_retries=_resolve_max_retries())
    kwargs: dict = {
        "model": mdl,
        "messages": [{"role": "user", "content": prompt}],
        "max_completion_tokens": max_tokens,
        # Force a single non-streamed response: some OpenAI-compatible gateways
        # default to SSE streaming when `stream` is omitted, but the result here
        # is always read as resp.choices[0]. Same fix as _call_openai_compat
        # (#1223) — this path feeds the --dedup-llm tiebreaker.
        "stream": False,
    }
    temperature = _resolve_temperature(cfg.get("temperature", 0), mdl)
    if temperature is not None:
        kwargs["temperature"] = temperature
    if cfg.get("reasoning_effort"):
        kwargs["reasoning_effort"] = cfg["reasoning_effort"]
    # Custom providers can override via providers.json `extra_body`; falls back
    # to the moonshot default to preserve existing behavior.

View on GitHub (pinned to 7fe58b0b0f)

Solutions

1. Install the extra: `uv tool install "graphifyy[openai]" --force` or `pip install openai`.
2. Double-check the backend string for typos - an unrecognized name falls into this branch and misleadingly demands the openai package.
3. Verify with `python -c "from openai import OpenAI"` in the graphify interpreter.

Example fix

# before
backend = "openia"   # typo -> falls through to OpenAI branch -> ImportError

# after
backend = "openai"    # and ensure: pip install openai

import importlib.util
if importlib.util.find_spec("openai") is None:
    raise SystemExit("OpenAI-compatible backends need the openai package: pip install openai")

try:
    result = call_llm(prompt, backend="openai")
except ImportError as exc:
    if "openai" in str(exc):
        raise SystemExit(f"Missing optional dep: {exc}") from exc
    raise

When it happens

Trigger: `from openai import OpenAI` fails while handling backends openai/gemini/kimi/ollama (llm.py:2707-2709). Also triggered indirectly: an unknown backend string falls through the explicit branches and reaches this import, so a typo like 'openia' produces this same ImportError.

Common situations: Using the ollama backend (local, no API key) without realizing graphify drives it through the openai client library; typo'd backend names in providers.json silently falling through; base-package installs without the [openai] extra.

Related errors

• the 'boto3' package is required for this backend but is not
• psycopg is required for --postgres. Install with: pip instal
• watchdog not installed. Run: pip install watchdog
• the '{pkg}' package is required for this backend but is not
• Azure OpenAI requires the openai package. Run: pip install o

AI-assisted analysis of Graphify-Labs/graphify@7fe58b0b0f (2026-08-14). Data as JSON: /api/errors/7fc3a7208e62fad2. Report an issue: GitHub.