pypa/pip · error · TypeError

Could not find adapter for

Error message

Could not find adapter for {registry} and {ob}

What it means

Raised as TypeError in _find_adapter() at line 3498 when no adapter is registered for any type in the MRO of the given object. _find_adapter walks `inspect.getmro(ob.__class__)` looking for a match in the registry dict; if none matches, it raises. This is an internal function used primarily for namespace handler lookup via _namespace_handlers.

Solutions

  1. Register a namespace handler for the custom importer type via register_namespace_handler(importer_type, handler).
  2. Use standard import machinery (FileFinder, zipimporter) that pkg_resources already supports.
  3. If using a custom sys.path importer, ensure it subclasses a known importer type.
  4. Catch TypeError around namespace package operations and fall back to PEP 420 implicit namespaces.

Example fix

// before: custom importer not registered
from pkg_resources import _find_adapter, _namespace_handlers
adapter = _find_adapter(_namespace_handlers, my_custom_importer)
# TypeError: Could not find adapter for ...

// after
from pkg_resources import register_namespace_handler
register_namespace_handler(type(my_custom_importer), my_handler_fn)
Defensive patterns

Strategy: try-catch

Validate before calling

from pkg_resources import _namespace_handlers
def importer_has_handler(importer) -> bool:
    import inspect
    types = inspect.getmro(getattr(importer, '__class__', type(importer)))
    return any(t in _namespace_handlers for t in types)

Type guard

from pkg_resources import _namespace_handlers
import inspect
def is_registered_importer(importer) -> bool:
    mro = inspect.getmro(getattr(importer, '__class__', type(importer)))
    return any(t in _namespace_handlers for t in mro)

Try / catch

from pkg_resources import _find_adapter, _namespace_handlers
try:
    handler = _find_adapter(_namespace_handlers, importer)
except TypeError:
    handler = None  # no registered handler for this importer type

Prevention

When it happens

Trigger: An importer object on sys.path whose type (or any base type) is not registered in _namespace_handlers. This is triggered indirectly via _handle_ns -> _find_adapter(_namespace_handlers, importer) at line 2463. Can also fire if _find_adapter is called with a custom registry lacking a matching type.

Common situations: A custom or unusual path importer (meta path finder, custom loader) not registered via register_namespace_handler; running under a non-standard Python implementation; extremely old or non-compliant import hooks; this is usually an internal failure rather than a user-facing one.

Related errors

AI-assisted analysis of pypa/pip@f399c37189 (2026-08-08). Data as JSON: /api/errors/1d577a806beff210. Report an issue: GitHub.

Appendix: source

Thrown at src/pip/_vendor/pkg_resources/__init__.py:3498

def _always_object(classes):
    """
    Ensure object appears in the mro even
    for old-style classes.
    """
    if object not in classes:
        return classes + (object,)
    return classes


def _find_adapter(registry: Mapping[type, _AdapterT], ob: object) -> _AdapterT:
    """Return an adapter factory for `ob` from `registry`"""
    types = _always_object(inspect.getmro(getattr(ob, '__class__', type(ob))))
    for t in types:
        if t in registry:
            return registry[t]
    # _find_adapter would previously return None, and immediately be called.
    # So we're raising a TypeError to keep backward compatibility if anyone depended on that behaviour.
    raise TypeError(f"Could not find adapter for {registry} and {ob}")


def ensure_directory(path: StrOrBytesPath):
    """Ensure that the parent directory of `path` exists"""
    dirname = os.path.dirname(path)
    os.makedirs(dirname, exist_ok=True)


def _bypass_ensure_directory(path):
    """Sandbox-bypassing version of ensure_directory()"""
    if not WRITE_SUPPORT:
        raise OSError('"os.mkdir" not supported on this platform.')
    dirname, filename = split(path)
    if dirname and filename and not isdir(dirname):
        _bypass_ensure_directory(dirname)
        try:
            mkdir(dirname, 0o755)
        except FileExistsError:

View on GitHub (pinned to f399c37189)