alibaba/spring-ai-alibaba · error · IllegalArgumentException
模型缺少 name
Error message
模型缺少 name
What it means
FileModelConfigRepository.validateYamlModel() throws IllegalArgumentException "模型缺少 name" ("model missing name") when a parsed YamlModel has a null or blank name. The name is a required, non-blank identifier for the model and is also used in duplicate-name detection.
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:119
}
Map<Long, ModelConfigDO> map = new HashMap<>();
Set<Long> ids = new HashSet<>();
Set<String> names = new HashSet<>();
for (YamlModel m : root.models) {
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) {View on GitHub (pinned to f82da0b50f)
Solutions
- Add a non-blank `name` value to every model entry in the YAML file.
- Check for entries with name: "" or only whitespace and fill them in.
- Ensure indentation places `name` under the correct model entry.
- Also ensure the name is unique — duplicate names are rejected by the names set.
Example fix
// before (yaml)
- id: 2
name: ""
// after (yaml)
- id: 2
name: qwen-max Defensive patterns
Strategy: validation
Validate before calling
models.forEach(m -> {
if (m.name == null || m.name.isBlank()) throw new IllegalArgumentException("model id=" + m.id + " missing name");
}); Type guard
static boolean hasName(YamlModel m) { return m != null && m.name != null && !m.name.isBlank(); } Try / catch
try { repo = FileModelConfigRepository.loadFromFile(path); }
catch (IllegalArgumentException e) { log.error("Model config invalid: {}", e.getMessage()); throw new ConfigurationException(e); } Prevention
- Reject blank strings, not just null, when validating YAML text fields
- Enforce unique names in CI along with presence checks
- Document that `name` is the local alias and must be human-meaningful
- Fail fast at config load time rather than at first model use
When it happens
Trigger: Loading the models YAML when a model entry has no `name` key, or name is present but empty/whitespace (name: "" or name: " ").
Common situations: Adding a new model block and leaving name blank; YAML anchoring/templating producing empty strings; accidental deletion of the name line during editing.
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
AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09).
Data as JSON: /api/errors/3ae55c23e8df8b13.
Report an issue: GitHub.