pypa/pip · error · ClassNotFound

no lexer for alias found

Error message

no lexer for alias {_alias!r} found

What it means

Raised by find_lexer_class_by_name when the alias argument is falsy (empty string or None) before any lookup is attempted. An empty alias is treated as 'not found' immediately at lexers/__init__.py:95-96. Returns ClassNotFound. This guards against silent acceptance of an empty alias.

Solutions

1. Validate that the alias is a non-empty string before calling.
2. Set a sensible default alias in your config rather than leaving it blank.
3. Strip and check: if not alias.strip(): raise your own error with context.

Example fix

# before
lexer_cls = find_lexer_class_by_name(user_input)
# after
alias = (user_input or '').strip()
if not alias:
    raise ValueError('language alias is required')
lexer_cls = find_lexer_class_by_name(alias)

if not alias or not str(alias).strip():
    raise ValueError('lexer alias must be a non-empty string')

def is_nonempty_alias(alias) -> bool:
    return bool(alias and str(alias).strip())

from pip._vendor.pygments.util import ClassNotFound
try:
    cls = find_lexer_class_by_name(alias)
except ClassNotFound:
    cls = None

When it happens

Trigger: Calling find_lexer_class_by_name('') or find_lexer_class_by_name(None). The 'if not _alias' check trips before the builtin/plugin search.

Common situations: Reading a language identifier from config that was left blank; variable unset before the call; whitespace-trimmed input that became empty.

Related errors

• lex() argument must be a lexer instance, not a class
• excclass option is not an exception class
• filter not found
• format() argument must be a formatter instance, not a class
• no formatter found for file name

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

Appendix: source

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

    for cls in find_plugin_lexers():
        if cls.name == name:
            return cls


def find_lexer_class_by_name(_alias):
    """
    Return the `Lexer` subclass that has `alias` in its aliases list, without
    instantiating it.

    Like `get_lexer_by_name`, but does not instantiate the class.

    Will raise :exc:`pygments.util.ClassNotFound` if no lexer with that alias is
    found.

    .. versionadded:: 2.2
    """
    if not _alias:
        raise ClassNotFound(f'no lexer for alias {_alias!r} found')
    # lookup builtin lexers
    for module_name, name, aliases, _, _ in LEXERS.values():
        if _alias.lower() in aliases:
            if name not in _lexer_cache:
                _load_lexers(module_name)
            return _lexer_cache[name]
    # continue with lexers from setuptools entrypoints
    for cls in find_plugin_lexers():
        if _alias.lower() in cls.aliases:
            return cls
    raise ClassNotFound(f'no lexer for alias {_alias!r} found')


def get_lexer_by_name(_alias, **options):
    """
    Return an instance of a `Lexer` subclass that has `alias` in its
    aliases list. The lexer is given the `options` at its
    instantiation.

View on GitHub (pinned to f399c37189)