pytest-dev/pytest · error · UsageError

' ' is not recognized as a logging level name for ' '…

Error message

'{log_level}' is not recognized as a logging level name for '{setting_name}'. Please consider passing the logging level num instead.

What it means

logging.py:643 raises UsageError when the configured log_level (from log_level or log_cli_level ini options) is a string that is neither a numeric nor a recognized logging level name (CRITICAL/ERROR/WARNING/INFO/DEBUG/NOTSET). The code tries int(getattr(logging, log_level, log_level)); if that raises ValueError, the name is invalid.

Solutions

Use a standard level name: CRITICAL, ERROR, WARNING, INFO, DEBUG, NOTSET (case-insensitive).
Pass a numeric level (e.g. --log-level=15) if you need a custom verbosity.
Check for stray whitespace/typos in the ini value.

Example fix

// before
# pytest.ini
log_level = verbose
// after
log_level = DEBUG

Defensive patterns

Strategy: validation

Validate before calling

import logging
VALID = {'CRITICAL','ERROR','WARNING','INFO','DEBUG','NOTSET'}
def validate_level(level: str) -> str:
    if not (level.upper() in VALID or level.isdigit()):
        raise ValueError(f'invalid log level {level!r}; use {VALID} or an int')
    return level

Type guard

def is_valid_log_level(v) -> bool:
    return isinstance(v, int) or (isinstance(v, str) and (v.upper() in {'CRITICAL','ERROR','WARNING','INFO','DEBUG','NOTSET'} or v.isdigit()))

Prevention

Use standard logging level names in ini files.
Use numeric levels for custom verbosity.
Validate config-driven level names at startup.

When it happens

Trigger: Setting log_level = VERBOSE or log_cli_level = info_t in pytest.ini / pyproject.toml / CLI --log-level; typo in a level name; passing a level that is a custom int but as an invalid string.

Common situations: Typos like 'warnging'; using framework-specific level names (e.g. 'VERBOSE' from a third-party logger) that are not on the standard logging module; copy-pasting level names with trailing whitespace.

Related errors

AI-assisted analysis of pytest-dev/pytest@0d6fbdeffa (2026-08-11). Data as JSON: /api/errors/afdd1a4b5b60ffa8. Report an issue: GitHub.

Appendix: source

Thrown at src/_pytest/logging.py:643


def get_log_level_for_setting(config: Config, *setting_names: str) -> int | None:
    for setting_name in setting_names:
        log_level = config.getoption(setting_name)
        if log_level is None:
            log_level = config.getini(setting_name)
        if log_level:
            break
    else:
        return None

    if isinstance(log_level, str):
        log_level = log_level.upper()
    try:
        return int(getattr(logging, log_level, log_level))
    except ValueError as e:
        # Python logging does not recognise this as a logging level
        raise UsageError(
            f"'{log_level}' is not recognized as a logging level name for "
            f"'{setting_name}'. Please consider passing the "
            "logging level num instead."
        ) from e


# run after terminalreporter/capturemanager are configured
@hookimpl(trylast=True)
def pytest_configure(config: Config) -> None:
    config.pluginmanager.register(LoggingPlugin(config), "logging-plugin")


class LoggingPlugin:
    """Attaches to the logging module and captures log messages for each test."""

    def __init__(self, config: Config) -> None:
        """Create a new plugin to capture log messages.

View on GitHub (pinned to 0d6fbdeffa)