pytest-dev/pytest · error · UsageError

'{log_level}' 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

Raised by `get_log_level_for_setting` when a configured logging level (e.g. `log_level`, `log_cli_level`) is a string that is neither a valid `logging` module constant (like "INFO") nor a parseable integer. pytest tries `int(getattr(logging, level, level))` and on ValueError raises UsageError suggesting to pass the numeric level instead.

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 98b357f69e)

Solutions

  1. Use a standard logging level name: DEBUG, INFO, WARNING, ERROR, CRITICAL (case-insensitive).
  2. Pass the numeric level instead, e.g. `--log-level=15` or `log_level = 15`.
  3. Register custom level names via `logging.addLevelName(num, "NAME")` before pytest configures logging (in an early conftest/pytest_addoption).

Example fix

// before
# pytest.ini
[pytest]
log_level = VERBOSE
// after
[pytest]
log_level = DEBUG
# or numeric: log_level = 10
Defensive patterns

Strategy: validation

Validate before calling

import logging

def validate_log_level(level):
    if isinstance(level, str):
        level = level.upper()
    val = getattr(logging, level, level) if isinstance(level, str) else level
    try:
        return int(val)
    except (TypeError, ValueError):
        raise ValueError(f"{level!r} is not a valid logging level")

Type guard

def is_valid_log_level(level) -> bool:
    import logging
    if isinstance(level, int):
        return level > 0
    if isinstance(level, str):
        return hasattr(logging, level.upper()) or level.isdigit()
    return False

Prevention

When it happens

Trigger: Setting `log_level = VERBOSE` or `log_cli_level = info-trace` in pytest.ini/pyproject.toml, or passing `--log-level=verbose` on the CLI. Also a bare string that is not an int and not a logging constant.

Common situations: Typos in level names. Using a custom logging level name defined at runtime that pytest cannot resolve at configure time. Copying a level name from another library (e.g. loguru) that isn't in stdlib logging.

Related errors

AI-assisted analysis of pytest-dev/pytest@98b357f69e (2026-08-04). Data as JSON: /data/errors/afdd1a4b5b60ffa8.json. Report an issue: GitHub.