{"record":{"id":"ff8f4edec03bff59","repo":"hiyouga/LlamaFactory","slug":"unknown-logging-level-env-level-str-ff8f4e","errorCode":null,"errorMessage":"Unknown logging level: {env_level_str}.","messagePattern":"Unknown logging level: (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/v1/utils/logging.py","lineNumber":51,"sourceCode":"\n    def info_rank0(self, *args, **kwargs) -> None:\n        self.info(*args, **kwargs)\n\n    def warning_rank0(self, *args, **kwargs) -> None:\n        self.warning(*args, **kwargs)\n\n    def warning_rank0_once(self, *args, **kwargs) -> None:\n        self.warning(*args, **kwargs)\n\n\ndef _get_default_logging_level() -> \"logging._Level\":\n    \"\"\"Return the default logging level.\"\"\"\n    env_level_str = os.getenv(\"LLAMAFACTORY_VERBOSITY\", None)\n    if env_level_str:\n        if env_level_str.upper() in logging._nameToLevel:\n            return logging._nameToLevel[env_level_str.upper()]\n        else:\n            raise ValueError(f\"Unknown logging level: {env_level_str}.\")\n\n    return _default_log_level\n\n\ndef _get_library_name() -> str:\n    return \".\".join(__name__.split(\".\")[:2])  # llamafactory.v1\n\n\ndef _get_library_root_logger() -> \"_Logger\":\n    return logging.getLogger(_get_library_name())\n\n\ndef _configure_library_root_logger() -> None:\n    \"\"\"Configure root logger using a stdout stream handler with an explicit format.\"\"\"\n    global _default_handler\n\n    with _thread_lock:\n        if _default_handler:  # already configured","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/v1/utils/logging.py#L33-L69","documentation":"ValueError from _get_default_logging_level (logging.py:51) when the LLAMAFACTORY_VERBOSITY environment variable holds a string that is not a standard Python logging level name (checked against logging._nameToLevel after uppercasing). The whole library's logging setup fails at import/first-logger time, so this can break unrelated imports.","triggerScenarios":"Exporting LLAMAFACTORY_VERBOSITY to values like 'verbose', 'normal', '20', 'WARNING ' (trailing space) or 'DEBUG2'. Numeric levels are rejected because only names in _nameToLevel match.","commonSituations":"CI/containers setting verbosity to app-specific words; copy-pasting verbosity values from other tools (transformers uses different names); scripts that export an integer verbosity.","solutions":["Set LLAMAFACTORY_VERBOSITY to a standard level name: DEBUG, INFO, WARNING, ERROR, or CRITICAL.","Unset the variable (unset LLAMAFACTORY_VERBOSITY) to fall back to the built-in default level.","If a script must pass numbers, map them to names before export (20 -> 'INFO')."],"exampleFix":"# before\nexport LLAMAFACTORY_VERBOSITY=verbose\n\n# after\nexport LLAMAFACTORY_VERBOSITY=DEBUG","handlingStrategy":"validation","validationCode":"import logging, os\nlvl = os.getenv(\"LLAMAFACTORY_VERBOSITY\")\nif lvl is not None and lvl.upper() not in logging._nameToLevel:\n    raise SystemExit(f\"LLAMAFACTORY_VERBOSITY must be one of {sorted(logging._nameToLevel)}\")","typeGuard":"def is_valid_verbosity(v: str) -> bool:\n    import logging\n    return v.upper() in logging._nameToLevel","tryCatchPattern":null,"preventionTips":["Use only standard level names (DEBUG/INFO/WARNING/ERROR/CRITICAL) in env files and CI.","Add an env-var lint step for containers that set LLAMAFACTORY_VERBOSITY."],"tags":["logging","environment","config","startup"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}