hiyouga/LlamaFactory · error · ValueError

Plugin configuration must have a 'name' field.

Error message

Plugin configuration must have a 'name' field.

What it means

`PluginConfig.name` is a property on the dict-with-attribute-access wrapper used for v1 plugin configs (init/peft/kernel/quant/optim etc.). Accessing `.name` on a plugin config that lacks a `name` key raises this ValueError, because the plugin registry is keyed by name.

Source

Thrown at src/llamafactory/v1/config/arg_utils.py:30

# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.


import json
from enum import StrEnum, unique


class PluginConfig(dict):
    """Dictionary that allows attribute access."""

    @property
    def name(self) -> str:
        """Plugin name."""
        if "name" not in self:
            raise ValueError("Plugin configuration must have a 'name' field.")

        return self["name"]


PluginArgument = PluginConfig | dict | str | None


@unique
class ModelClass(StrEnum):
    """Auto class for model config."""

    LLM = "llm"
    CLS = "cls"
    OTHER = "other"


@unique
class SampleBackend(StrEnum):

View on GitHub (pinned to f28afaf635)

Solutions

1. Add a `name` field to the plugin config, e.g. `quant_config: {name: bnb, ...}`
2. If building programmatically, set it at construction: `PluginConfig({"name": "lora", ...})`
3. Prefer `get_plugin_config()` from `arg_utils` (error 309's path) which validates the field once, early

Example fix

# before
cfg = PluginConfig({"lora_rank": 16})
print(cfg.name)  # ValueError

# after
cfg = PluginConfig({"name": "lora", "lora_rank": 16})
print(cfg.name)  # 'lora'

def has_name(cfg: dict) -> bool:
    return isinstance(cfg, dict) and "name" in cfg

from typing import TypeGuard

def is_valid_plugin_config(cfg: object) -> TypeGuard[dict]:
    return isinstance(cfg, dict) and "name" in cfg and isinstance(cfg["name"], str)

When it happens

Trigger: Constructing or deserializing a `PluginConfig` (or plain dict wrapped into one) without a `name` entry and then reading `.name`, typically when a plugin config dict was built from partial user input or merged YAML that dropped the field.

Common situations: Writing a plugin config inline in YAML and forgetting the `name:` line; a deep-merge or OmegaConf conversion losing the key; code that conditionally sets `name` after construction but reads it before.

Related errors

• Unknown backend: {model_args.infer_backend}
• world_size ({helper.get_world_size()}) must be divisible by
• mp_replicate_size * mp_shard_size must equal to world_size,
• world_size ({helper.get_world_size()}) must be divisible by
• dp_size * cp_size must equal to world_size, got {self.dp_siz

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