BerriAI/litellm · error · AttributeError

Utils module lazy import: unknown attribute {name!r}

Error message

Utils module lazy import: unknown attribute {name!r}

What it means

A dedicated handler, _lazy_import_utils_module, serves lazy imports for the utils module using its own import map (_UTILS_MODULE_IMPORT_MAP) and its own globals cache. If the requested name is not a key in that map, it raises AttributeError 'Utils module lazy import: unknown attribute <name>'. Utils attributes are whitelisted explicitly; anything outside the whitelist cannot be lazily loaded from litellm.utils via this path.

Source

Thrown at litellm/_lazy_imports.py:339

    """Handler for litellm_logging module (Logging, modify_integration)"""
    return _generic_lazy_import(name, _LITELLM_LOGGING_IMPORT_MAP, "Litellm logging")


def _lazy_import_llm_provider_logic(name: str) -> Any:
    """Handler for LLM provider logic functions (get_llm_provider, etc.)"""
    return _generic_lazy_import(name, _LLM_PROVIDER_LOGIC_IMPORT_MAP, "LLM provider logic")


def _lazy_import_utils_module(name: str) -> Any:
    """
    Handler for utils module lazy imports.

    This uses a custom implementation because utils module needs to use
    _get_utils_globals() instead of get_litellm_globals() for caching.
    """
    # Check if this attribute exists in our map
    if name not in _UTILS_MODULE_IMPORT_MAP:
        raise AttributeError(f"Utils module lazy import: unknown attribute {name!r}")

    # Get the cache (where we store imported things) - use utils globals
    _globals: Final = _get_utils_globals()

    # If we've already imported it, just return the cached version
    if name in _globals:
        return _globals[name]

    # Look up where to find this attribute
    module_path, attr_name = _UTILS_MODULE_IMPORT_MAP[name]

    # Import the module
    if module_path.startswith("."):
        module = importlib.import_module(module_path, package="litellm")
    else:
        module = importlib.import_module(module_path)

    # Get the actual attribute from the module

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Import the utility from its defining module (e.g. from litellm.litellm_core_utils.xxx import yyy) found by searching the repo/package.
2. Check _UTILS_MODULE_IMPORT_MAP in your installed litellm/_lazy_imports.py to see exactly which utils names are available lazily.
3. Upgrade or pin litellm to a version where the name is mapped.
4. Replace usage of internal/private helpers with the public API equivalent.

Example fix

# before
import litellm
val = litellm.utils._get_hidden_params  # AttributeError: Utils module lazy import: unknown attribute ...

# after
from litellm.litellm_core_utils.litellm_logging import _get_hidden_params  # import from real home

from litellm import _lazy_imports
utils_names = set(_lazy_imports._UTILS_MODULE_IMPORT_MAP)
if name not in utils_names:
    raise ImportError(f'{name!r} not lazily exported from litellm.utils; import from its defining module')

import litellm

def get_util(name: str):
    try:
        return getattr(litellm.utils, name)
    except AttributeError:
        return None  # not in the lazy map for this version

try:
    fn = getattr(litellm.utils, name)
except AttributeError as e:
    if 'Utils module lazy import' in str(e):
        fn = import_from_defining_module(name)  # fallback lookup
    else:
        raise

When it happens

Trigger: Doing litellm.utils.<name> or a top-level access routed to the utils handler where <name> is not in _UTILS_MODULE_IMPORT_MAP — e.g. a private helper, a function that lives elsewhere, or a name removed in the current release.

Common situations: Code written against older litellm where utils re-exported more names; importing internal helpers (underscore functions) that were never part of the public map; refactors that moved functions out of litellm.utils without callers updating.

Related errors

• module {__name__!r} has no attribute {name!r}
• {category} lazy import: unknown attribute {name!r}
• LLM client cache lazy import: unknown attribute {name!r}
• HTTP handlers lazy import: unknown attribute {name!r}
• module {__name__!r} has no attribute {name!r}

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/cfc3ba650e1156db. Report an issue: GitHub.