alibaba/spring-ai-alibaba · error · IllegalArgumentException

模型缺少 modelName

Error message

模型缺少 modelName

What it means

FileModelConfigRepository.validateYamlModel() throws IllegalArgumentException "模型缺少 modelName" ("model missing modelName") when the YamlModel's modelName field is null or blank. modelName is the actual upstream model identifier (e.g. qwen-max, gpt-4o) sent to the provider API and is distinct from the local display `name`.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-start/src/main/java/com/alibaba/cloud/ai/studio/admin/repository/impl/FileModelConfigRepository.java:125

            validateYamlModel(m, ids, names);
            ModelConfigDO entity = toEntity(m);
            map.put(entity.getId(), entity);
        }
        return map;
    }
    
    private void validateYamlModel(YamlModel m, Set<Long> ids, Set<String> names) {
        if (m.id == null) {
            throw new IllegalArgumentException("模型缺少 id");
        }
        if (m.name == null || m.name.isBlank()) {
            throw new IllegalArgumentException("模型缺少 name");
        }
        if (m.provider == null || m.provider.isBlank()) {
            throw new IllegalArgumentException("模型缺少 provider");
        }
        if (m.modelName == null || m.modelName.isBlank()) {
            throw new IllegalArgumentException("模型缺少 modelName");
        }
        //        if (m.baseUrl == null || m.baseUrl.isBlank()) throw new IllegalArgumentException("模型缺少 baseUrl");
        if (m.apiKey == null || m.apiKey.isBlank()) {
            throw new IllegalArgumentException("模型缺少 apiKey");
        }
        if (!ids.add(m.id)) {
            throw new IllegalArgumentException("重复的模型 id: " + m.id);
        }
        if (!names.add(m.name)) {
            throw new IllegalArgumentException("重复的模型 name: " + m.name);
        }
        if (m.status == null) {
            m.status = 1;
        }
    }
    
    private ModelConfigDO toEntity(YamlModel m) {
        ModelConfigDO.ModelConfigDOBuilder b = ModelConfigDO.builder().id(m.id).name(m.name)

View on GitHub (pinned to f82da0b50f)

Solutions

1. Add the upstream `modelName` (e.g. qwen-max) to the model entry in the YAML.
2. Do not confuse it with the local alias `name` — both are required.
3. Check the YAML key spelling/casing matches the YamlModel field (modelName).
4. Remove blank values (modelName: "").

Example fix

// before (yaml)
  - id: 4
    name: my-qwen
    provider: dashscope
// after (yaml)
  - id: 4
    name: my-qwen
    provider: dashscope
    modelName: qwen-max

models.forEach(m -> {
    if (m.modelName == null || m.modelName.isBlank()) throw new IllegalArgumentException("model '" + m.name + "' missing modelName");
});

static boolean hasModelName(YamlModel m) { return m != null && m.modelName != null && !m.modelName.isBlank(); }

try { repo = FileModelConfigRepository.loadFromFile(path); }
catch (IllegalArgumentException e) { log.error("Model config invalid: {}", e.getMessage()); throw new ConfigurationException(e); }

When it happens

Trigger: Loading the models YAML where an entry defines id/name/provider but no `modelName` key, or modelName is blank, so the framework cannot know which upstream model to invoke.

Common situations: Copying an entry and deleting modelName; confusing `name` (local alias) with `modelName` (provider model id) and only filling one; YAML key typo (model-name vs modelName) if relaxed binding is not applied.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• 模型缺少 id
• 模型缺少 name
• 模型缺少 provider
• BuildToolSchemaError
• WORKFLOW_CONFIG_ILLEGAL

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/7c477a876e3681e3. Report an issue: GitHub.