hiyouga/LlamaFactory · error · ValueError

Unknown logging level: {env_level_str}.

Error message

Unknown logging level: {env_level_str}.

What it means

LlamaFactory reads the LLAMAFACTORY_VERBOSITY environment variable to set its log level. The value (case-insensitive) must be a standard Python logging level name such as DEBUG, INFO, WARNING, ERROR, or CRITICAL; anything else raises ValueError at logger initialization, before any training output appears.

Source

Thrown at src/llamafactory/extras/logging.py:88

    def info_rank0(self, *args, **kwargs) -> None:
        self.info(*args, **kwargs)

    def warning_rank0(self, *args, **kwargs) -> None:
        self.warning(*args, **kwargs)

    def warning_rank0_once(self, *args, **kwargs) -> None:
        self.warning(*args, **kwargs)


def _get_default_logging_level() -> "logging._Level":
    r"""Return the default logging level."""
    env_level_str = os.getenv("LLAMAFACTORY_VERBOSITY", None)
    if env_level_str:
        if env_level_str.upper() in logging._nameToLevel:
            return logging._nameToLevel[env_level_str.upper()]
        else:
            raise ValueError(f"Unknown logging level: {env_level_str}.")

    return _default_log_level


def _get_library_name() -> str:
    return __name__.split(".")[0]


def _get_library_root_logger() -> "_Logger":
    return logging.getLogger(_get_library_name())


def _configure_library_root_logger() -> None:
    r"""Configure root logger using a stdout stream handler with an explicit format."""
    global _default_handler

    with _thread_lock:
        if _default_handler:  # already configured

View on GitHub (pinned to f28afaf635)

Solutions

1. Unset or fix the variable: export LLAMAFACTORY_VERBOSITY=INFO (or DEBUG/WARNING/ERROR/CRITICAL).
2. Check shell profile, Dockerfile ENV, docker-compose, and CI env blocks for the misspelled value.
3. Use exact Python logging level names only — numeric levels are not accepted by this code path.

Example fix

# before
ENV LLAMAFACTORY_VERBOSITY=verbose

# after
ENV LLAMAFACTORY_VERBOSITY=DEBUG

import logging, os

level = os.getenv("LLAMAFACTORY_VERBOSITY")
if level is not None:
    assert level.upper() in logging._nameToLevel, f"bad LLAMAFACTORY_VERBOSITY: {level}"

When it happens

Trigger: Exporting LLAMAFACTORY_VERBOSITY=verbose / =10 / =Info. (trailing punctuation) in the shell, Dockerfile, or .env; CI pipelines injecting lowercase-with-typos values; values like 'warn' that Python accepts via logging.getLevelName but not via the _nameToLevel name map used here ('WARN' actually works uppercased; 'warn' lowercased also works via .upper(), but 'verbose' does not).

Common situations: Copying verbosity settings from other frameworks (transformers uses TRANSFORMERS_VERBOSITY with different accepted values); Docker/k8s env misconfiguration; values like 'TRACE' or 'ALL' that Python logging does not define.

Related errors

• Unknown logging level: {env_level_str}.
• Megatron Bridge arguments are missing. Please set USE_MEGATR
• Please upgrade `transformers` to 4.34.0
• Unable to process key {key}
• bf16 and fp16 cannot be both True.

AI-assisted analysis of hiyouga/LlamaFactory@f28afaf635 (2026-08-14). Data as JSON: /api/errors/e3e5a90fa29a5a90. Report an issue: GitHub.