alibaba/spring-ai-alibaba · error · IllegalArgumentException

模型缺少 apiKey

Error message

模型缺少 apiKey

What it means

FileModelConfigRepository.validateYamlModel validates each model entry loaded from the YAML model-config file. When an entry has a null or blank apiKey, it throws this IllegalArgumentException to abort loading, since most model providers cannot be invoked without credentials. The loadFromFile caller fails fast rather than registering an unusable model.

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:129

        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)
                .provider(m.provider.toLowerCase()).modelName(m.modelName).baseUrl(m.baseUrl)
                .apiKey(environment != null ? environment.resolvePlaceholders(m.apiKey) : m.apiKey).status(m.status)
                .createTime(LocalDateTime.now()).updateTime(LocalDateTime.now());
        

View on GitHub (pinned to f82da0b50f)

Solutions

1. Open the models YAML file loaded by FileModelConfigRepository and set a non-blank apiKey for the offending model entry
2. If the key comes from an environment variable or config placeholder, verify it is actually set in the runtime environment and resolved at load time
3. Temporarily comment out or remove the incomplete model entry so the remaining valid models load
4. Check the exception message chain / file watch logs to identify which model id is missing the key

Example fix

// before (models.yml)
models:
  - id: 1
    name: qwen-max
    modelName: qwen-max
    apiKey:
// after
models:
  - id: 1
    name: qwen-max
    modelName: qwen-max
    apiKey: sk-xxxxxxxxxxxxxxxx

// Java: check before loading/registering
if (model.getApiKey() == null || model.getApiKey().isBlank()) {
    throw new IllegalStateException("Skip model " + model.getName() + ": apiKey missing");
}

boolean hasApiKey(m) { return m != null && m.getApiKey() != null && !m.getApiKey().isBlank(); }

try {
    repository.loadFromFile(path);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("apiKey")) {
        log.error("Model config file has a model without apiKey: {}", e.getMessage());
    }
}

When it happens

Trigger: Calling loadFromFile (at repository startup or file reload) when the YAML models file contains a model entry whose apiKey field is missing, empty (""), or whitespace-only.

Common situations: Hand-editing the YAML and omitting apiKey; copying a model entry as a template without filling in the key; environment-specific key injection failing (placeholder left as ${DASHSCOPE_API_KEY} unresolved or blank); sharing sanitized config files with keys stripped.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

• 模型缺少 id
• 模型缺少 name
• 模型缺少 provider
• 模型缺少 modelName
• 重复的模型 id:

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