{"record":{"id":"71568a4732b316e6","repo":"pypa/pip","slug":"error-when-loading-custom-formatter-err","errorCode":null,"errorMessage":"error when loading custom formatter: {err}","messagePattern":"error when loading custom formatter: (.+?)","errorType":"exception","errorClass":"ClassNotFound","httpStatus":null,"severity":"error","filePath":"src/pip/_vendor/pygments/formatters/__init__.py","lineNumber":115,"sourceCode":"    .. versionadded:: 2.2\n    \"\"\"\n    try:\n        # This empty dict will contain the namespace for the exec'd file\n        custom_namespace = {}\n        with open(filename, 'rb') as f:\n            exec(f.read(), custom_namespace)\n        # Retrieve the class `formattername` from that namespace\n        if formattername not in custom_namespace:\n            raise ClassNotFound(f'no valid {formattername} class found in {filename}')\n        formatter_class = custom_namespace[formattername]\n        # And finally instantiate it with the options\n        return formatter_class(**options)\n    except OSError as err:\n        raise ClassNotFound(f'cannot read {filename}: {err}')\n    except ClassNotFound:\n        raise\n    except Exception as err:\n        raise ClassNotFound(f'error when loading custom formatter: {err}')\n\n\ndef get_formatter_for_filename(fn, **options):\n    \"\"\"\n    Return a :class:`.Formatter` subclass instance that has a filename pattern\n    matching `fn`. The formatter is given the `options` at its instantiation.\n\n    Will raise :exc:`pygments.util.ClassNotFound` if no formatter for that filename\n    is found.\n    \"\"\"\n    fn = basename(fn)\n    for modname, name, _, filenames, _ in FORMATTERS.values():\n        for filename in filenames:\n            if _fn_matches(fn, filename):\n                if name not in _formatter_cache:\n                    _load_formatters(modname)\n                return _formatter_cache[name](**options)\n    for _name, cls in find_plugin_formatters():","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_vendor/pygments/formatters/__init__.py#L97-L133","documentation":"Raised by load_formatter_from_file for any Exception during exec() of the file other than OSError or an explicit ClassNotFound. This catches SyntaxError, import errors, instantiation errors, or exceptions thrown while the formatter class is being instantiated. The original exception message is folded into the ClassNotFound message at __init__.py:114-115.","triggerScenarios":"The custom formatter file has a SyntaxError, raises ImportError (missing dependency), references undefined names, or its __init__ raises an error during formatter_class(**options).","commonSituations":"Formatter depends on a package not installed in the environment; Python 2 vs 3 syntax; class __init__ rejects the options dict; typo in an attribute reference inside the file.","solutions":["Import the file standalone (python -c \"exec(open('myfmt.py').read())\") to see the real underlying exception.","Install any missing dependencies the formatter imports.","Fix syntax errors in the file.","Ensure the options passed match what the formatter's __init__ expects."],"exampleFix":"# diagnose the hidden error\nimport traceback\ntry:\n    load_formatter_from_file('myfmt.py')\nexcept Exception:\n    traceback.print_exc()\n# then fix the root cause (e.g. add missing import) in myfmt.py","handlingStrategy":"try-catch","validationCode":"null","typeGuard":"null","tryCatchPattern":"from pip._vendor.pygments.util import ClassNotFound\ntry:\n    fmt = load_formatter_from_file(path)\nexcept ClassNotFound as e:\n    # surface the wrapped message to debug the real cause\n    import logging; logging.exception('formatter load failed')\n    raise","preventionTips":["exec the file standalone first to catch syntax/import errors.","Ensure all dependencies the formatter imports are installed."],"tags":["python","pygments","formatter","debugging","vendored"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}