{"record":{"id":"cfc3ba650e1156db","repo":"BerriAI/litellm","slug":"utils-module-lazy-import-unknown-attribute-name","errorCode":null,"errorMessage":"Utils module lazy import: unknown attribute {name!r}","messagePattern":"Utils module lazy import: unknown attribute (.+?)","errorType":"exception","errorClass":"AttributeError","httpStatus":null,"severity":"error","filePath":"litellm/_lazy_imports.py","lineNumber":339,"sourceCode":"    \"\"\"Handler for litellm_logging module (Logging, modify_integration)\"\"\"\n    return _generic_lazy_import(name, _LITELLM_LOGGING_IMPORT_MAP, \"Litellm logging\")\n\n\ndef _lazy_import_llm_provider_logic(name: str) -> Any:\n    \"\"\"Handler for LLM provider logic functions (get_llm_provider, etc.)\"\"\"\n    return _generic_lazy_import(name, _LLM_PROVIDER_LOGIC_IMPORT_MAP, \"LLM provider logic\")\n\n\ndef _lazy_import_utils_module(name: str) -> Any:\n    \"\"\"\n    Handler for utils module lazy imports.\n\n    This uses a custom implementation because utils module needs to use\n    _get_utils_globals() instead of get_litellm_globals() for caching.\n    \"\"\"\n    # Check if this attribute exists in our map\n    if name not in _UTILS_MODULE_IMPORT_MAP:\n        raise AttributeError(f\"Utils module lazy import: unknown attribute {name!r}\")\n\n    # Get the cache (where we store imported things) - use utils globals\n    _globals: Final = _get_utils_globals()\n\n    # If we've already imported it, just return the cached version\n    if name in _globals:\n        return _globals[name]\n\n    # Look up where to find this attribute\n    module_path, attr_name = _UTILS_MODULE_IMPORT_MAP[name]\n\n    # Import the module\n    if module_path.startswith(\".\"):\n        module = importlib.import_module(module_path, package=\"litellm\")\n    else:\n        module = importlib.import_module(module_path)\n\n    # Get the actual attribute from the module","sourceCodeStart":321,"sourceCodeEnd":357,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/_lazy_imports.py#L321-L357","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Import the utility from its defining module (e.g. from litellm.litellm_core_utils.xxx import yyy) found by searching the repo/package.","Check _UTILS_MODULE_IMPORT_MAP in your installed litellm/_lazy_imports.py to see exactly which utils names are available lazily.","Upgrade or pin litellm to a version where the name is mapped.","Replace usage of internal/private helpers with the public API equivalent."],"exampleFix":"# before\nimport litellm\nval = litellm.utils._get_hidden_params  # AttributeError: Utils module lazy import: unknown attribute ...\n\n# after\nfrom litellm.litellm_core_utils.litellm_logging import _get_hidden_params  # import from real home","handlingStrategy":"type-guard","validationCode":"from litellm import _lazy_imports\nutils_names = set(_lazy_imports._UTILS_MODULE_IMPORT_MAP)\nif name not in utils_names:\n    raise ImportError(f'{name!r} not lazily exported from litellm.utils; import from its defining module')","typeGuard":"import litellm\n\ndef get_util(name: str):\n    try:\n        return getattr(litellm.utils, name)\n    except AttributeError:\n        return None  # not in the lazy map for this version","tryCatchPattern":"try:\n    fn = getattr(litellm.utils, name)\nexcept AttributeError as e:\n    if 'Utils module lazy import' in str(e):\n        fn = import_from_defining_module(name)  # fallback lookup\n    else:\n        raise","preventionTips":["Do not reach into litellm.utils for private/underscore helpers; they are outside the lazy whitelist.","After upgrades, grep the changelog/source for moved utils functions.","Centralize all litellm imports in one adapter module so renames are fixed in one place."],"tags":["litellm","python","attributeerror","lazy-import","utils"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}