{"id":"78468f233d41b03b","repo":"pytest-dev/pytest","slug":"pdbcls-could-not-import-value-r-exc","errorCode":null,"errorMessage":"--pdbcls: could not import {value!r}: {exc}","messagePattern":"--pdbcls: could not import (.+?): (.+?)","errorType":"exception","errorClass":"UsageError","httpStatus":null,"severity":"error","filePath":"src/_pytest/debugging.py","lineNumber":135,"sourceCode":"        usepdb_cls = cls._config.getvalue(\"usepdb_cls\")\n\n        if cls._wrapped_pdb_cls and cls._wrapped_pdb_cls[0] == usepdb_cls:\n            return cls._wrapped_pdb_cls[1]\n\n        if usepdb_cls:\n            modname, classname = usepdb_cls\n\n            try:\n                mod = importlib.import_module(modname)\n\n                # Handle --pdbcls=pdb:pdb.Pdb (useful e.g. with pdbpp).\n                parts = classname.split(\".\")\n                pdb_cls = getattr(mod, parts[0])\n                for part in parts[1:]:\n                    pdb_cls = getattr(pdb_cls, part)\n            except Exception as exc:\n                value = \":\".join((modname, classname))\n                raise UsageError(\n                    f\"--pdbcls: could not import {value!r}: {exc}\"\n                ) from exc\n        else:\n            import pdb\n\n            pdb_cls = pdb.Pdb\n\n        wrapped_cls = cls._get_pdb_wrapper_class(pdb_cls, capman)\n        cls._wrapped_pdb_cls = (usepdb_cls, wrapped_cls)\n        return wrapped_cls\n\n    @classmethod\n    def _get_pdb_wrapper_class(cls, pdb_cls, capman: CaptureManager | None):\n        import _pytest.config\n\n        class PytestPdbWrapper(pdb_cls):\n            _pytest_capman = capman\n            _continued = False","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/pytest-dev/pytest/blob/98b357f69e380da908740a212288d73b2ee06687/src/_pytest/debugging.py#L117-L153","documentation":"Raised when the --pdbcls command-line option (or usepdb_cls ini option) specifies a debugger class that cannot be imported or resolved. pytest takes a 'module:ClassName' (or 'module:dotted.path.Class') string, imports the module, then walks the dotted attribute path; any ImportError, AttributeError, or other exception during this is wrapped as a UsageError naming the offending value and the underlying exception.","triggerScenarios":"Running pytest --pdbcls=mydebugger:Pdb when 'mydebugger' isn't installed; --pdbcls=pdb:Nonexistent; --pdbcls=badmodule:goodpath.GoodClass where badmodule fails to import. The import/getattr block at line 125-132 raises, caught at 133-137.","commonSituations":"Specifying pdbpp/ipdb without installing them; typos in the module or class name; debugger class moved/renamed between versions; environment where the debugger package isn't installed; specifying a class path that requires a submodule not auto-imported.","solutions":["Install the debugger package: pip install pdbpp (or ipdb).","Verify the import works: python -c 'import mymodule; print(mymodule.MyPdb)'.","Use the default pdb: remove --pdbcls / usepdb_cls.","Double-check the class path including any intermediate attributes (e.g. 'module:pkg.Class')."],"exampleFix":"# before\npytest --pdbcls=ppdb:Pdb  # typo, package is pdbpp\n\n# after\npip install pdbpp\npytest --pdbcls=pdbpp:Pdb","handlingStrategy":"validation","validationCode":"import importlib\ndef resolve_pdbcls(spec: str):\n    modname, _, classname = spec.partition(':')\n    mod = importlib.import_module(modname)\n    obj = mod\n    for part in classname.split('.'):\n        obj = getattr(obj, part)\n    return obj\n# call before pytest: resolve_pdbcls('pdbpp:Pdb') to fail fast with a clear error","typeGuard":"import importlib\ndef pdbcls_resolvable(spec: str) -> bool:\n    try:\n        modname, _, classname = spec.partition(':')\n        obj = importlib.import_module(modname)\n        for part in classname.split('.'):\n            obj = getattr(obj, part)\n        return isinstance(obj, type)\n    except Exception:\n        return False","tryCatchPattern":"try:\n    cls = resolve_pdbcls(user_spec)\nexcept Exception as exc:\n    raise ValueError(f'--pdbcls: could not import {user_spec!r}: {exc}') from exc","preventionTips":["Install the debugger package (pip install pdbpp / ipdb) before referencing it in --pdbcls.","Validate the module:Class path with a one-liner: python -c 'import mod; print(mod.Cls)'.","Default to the builtin pdb when the custom debugger isn't strictly needed."],"tags":["pytest","debugging","cli","pdbcls","import","usage-error"],"analyzedSha":"98b357f69e380da908740a212288d73b2ee06687","analyzedAt":"2026-08-04T20:26:34.442Z","schemaVersion":2}