pypa/pip · error · ClassNotFound

error when loading custom lexer: {err}

Error message

error when loading custom lexer: {err}

What it means

Raised by load_lexer_from_file as a catch-all when exec() of the file raises any exception other than OSError or ClassNotFound (SyntaxError, ImportError, NameError, etc.). The original exception text is embedded in the message.

Source

Thrown at src/pip/_vendor/pygments/lexers/__init__.py:166

    .. versionadded:: 2.2
    """
    try:
        # This empty dict will contain the namespace for the exec'd file
        custom_namespace = {}
        with open(filename, 'rb') as f:
            exec(f.read(), custom_namespace)
        # Retrieve the class `lexername` from that namespace
        if lexername not in custom_namespace:
            raise ClassNotFound(f'no valid {lexername} class found in {filename}')
        lexer_class = custom_namespace[lexername]
        # And finally instantiate it with the options
        return lexer_class(**options)
    except OSError as err:
        raise ClassNotFound(f'cannot read {filename}: {err}')
    except ClassNotFound:
        raise
    except Exception as err:
        raise ClassNotFound(f'error when loading custom lexer: {err}')


def find_lexer_class_for_filename(_fn, code=None):
    """Get a lexer for a filename.

    If multiple lexers match the filename pattern, use ``analyse_text()`` to
    figure out which one is more appropriate.

    Returns None if not found.
    """
    matches = []
    fn = basename(_fn)
    for modname, name, _, filenames, _ in LEXERS.values():
        for filename in filenames:
            if _fn_matches(fn, filename):
                if name not in _lexer_cache:
                    _load_lexers(modname)
                matches.append((_lexer_cache[name], filename))

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Byte-compile the file (python -m py_compile mylex.py) to find syntax errors.
2. Run the file directly to see the real traceback.
3. Install missing imports reported in the embedded message.

Example fix

# before: mylex.py has `from missing_pkg import X`
# diagnose:
#   python mylex.py -> ModuleNotFoundError
# after: install missing_pkg or remove the import

import py_compile
def compiles_clean(filename):
    try:
        py_compile.compile(filename, doraise=True)
        return True
    except py_compile.PyCompileError:
        return False

from pygments.util import ClassNotFound
from pygments.lexers import TextLexer
try:
    lex = load_lexer_from_file(fn, name)
except ClassNotFound as e:
    if 'error when loading' in str(e):
        log.error('custom lexer failed: %s', e)
        lex = TextLexer()
    else:
        raise

When it happens

Trigger: The custom lexer file has a syntax error, an unresolved import, or any runtime error during module execution.

Common situations: Typo introduced while editing the lexer file; depending on a package not installed in the env; Python-version-incompatible syntax in the file.

Related errors

• no valid {lexername} class found in {filename}
• no valid {formattername} class found in {filename}
• error when loading custom formatter: {err}
• cannot read {filename}: {err}
• lex() argument must be a lexer instance, not a class

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/30661ffcce68335b.json. Report an issue: GitHub.