alibaba/spring-ai-alibaba · error · IllegalArgumentException

参数 ${parameterName} 的值 ${value} 无法转换为类型 ${type}

Error message

参数 ${parameterName} 的值 ${value} 无法转换为类型 ${type}

What it means

ModelConfigInfo.getParameter() retrieves a typed parameter from the model config map and attempts an unchecked cast `(T) value`. If the stored value's runtime type does not match the requested type T, the ClassCastException is caught and rethrown as IllegalArgumentException: "参数 X 的值 V 无法转换为类型 T" ("value of parameter X cannot be converted to type T"). It is a type-safety guard over the untyped parameter map.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-start/src/main/java/com/alibaba/cloud/ai/studio/admin/dto/ModelConfigInfo.java:75

    /**
     * 获取指定参数值（指定类型）
     *
     * @param parameterName 参数名
     * @param type         期望的类型
     * @param <T>          类型参数
     * @return 参数值
     */
    @SuppressWarnings("unchecked")
    public <T> T getParameter(String parameterName, Class<T> type) {
        Object value = parameters.get(parameterName);
        if (value == null) {
            return null;
        }
        
        try {
            return (T) value;
        } catch (ClassCastException e) {
            throw new IllegalArgumentException(
                String.format("参数 %s 的值 %s 无法转换为类型 %s", 
                    parameterName, value, type.getSimpleName()), e);
        }
    }

    /**
     * 设置参数值
     *
     * @param parameterName 参数名
     * @param value        参数值
     */
    public void setParameter(String parameterName, Object value) {
        parameters.put(parameterName, value);
    }

    /**
     * 检查是否包含指定参数
     *

View on GitHub (pinned to f82da0b50f)

Solutions

1. Fix the config source so the value has the correct type (unquote numbers in YAML, e.g. temperature: 0.7 not temperature: "0.7").
2. Convert instead of casting: use Number intermediate (`((Number) value).doubleValue()`) or a converter before the cast.
3. Validate parameter types when loading/parsing the config file rather than at lookup time.
4. Check which caller passes the wrong expected type T and align it with what is actually stored.

Example fix

// before
return (T) value;
// after
if (type == Double.class && value instanceof Number n) { return (T) Double.valueOf(n.doubleValue()); }
return (T) value;

Object v = params.get(name);
if (v != null && !(type.isInstance(v)) && !(v instanceof Number)) {
    throw new IllegalArgumentException("param " + name + " has type " + v.getClass());
}

static <T> boolean isOfType(Object v, Class<T> t) { return v == null || t.isInstance(v) || (Number.class.isAssignableFrom(t) && v instanceof Number); }

try { return config.getParameter("temperature", Double.class); } catch (IllegalArgumentException e) { log.warn("bad param type, using default", e); return 0.7d; }

When it happens

Trigger: Calling getParameter("temperature", Double.class) when the map holds a String (e.g. "0.7" parsed from YAML/JSON without conversion), or getParameter(..., Integer.class) on a Double/Long value stored by a deserializer.

Common situations: YAML/JSON config files where numbers were written as quoted strings; different writers storing the same parameter with different numeric types; user-edited model config with wrong value type.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• maxConcurrency must be at least 1, but got:
• No default detector for PII type: ${type}
• SkillRegistry cannot be null
• SkillRegistry cannot be null
• SkillRegistry cannot be null

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