{"record":{"id":"5dafcf96f561a1c8","repo":"chinabugotech/hutool","slug":"failed-to-create-aiconfig-instance","errorCode":null,"errorMessage":"Failed to create AIConfig instance","messagePattern":"Failed to create AIConfig instance","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"hutool-ai/src/main/java/cn/hutool/ai/core/AIConfigBuilder.java","lineNumber":49,"sourceCode":"\n\t/**\n\t * 构造\n\t *\n\t * @param modelName 模型厂商的名称（注意不是指具体的模型）\n\t */\n\tpublic AIConfigBuilder(final String modelName) {\n\t\ttry {\n\t\t\t// 获取配置类\n\t\t\tfinal Class<? extends AIConfig> configClass = AIConfigRegistry.getConfigClass(modelName);\n\t\t\tif (configClass == null) {\n\t\t\t\tthrow new IllegalArgumentException(\"Unsupported model: \" + modelName);\n\t\t\t}\n\n\t\t\t// 使用反射创建实例\n\t\t\tfinal Constructor<? extends AIConfig> constructor = configClass.getDeclaredConstructor();\n\t\t\tconfig = constructor.newInstance();\n\t\t} catch (final Exception e) {\n\t\t\tthrow new RuntimeException(\"Failed to create AIConfig instance\", e);\n\t\t}\n\t}\n\n\t/**\n\t * 设置apiKey\n\t *\n\t * @param apiKey apiKey\n\t * @return config\n\t * @since 5.8.38\n\t */\n\tpublic synchronized AIConfigBuilder setApiKey(final String apiKey) {\n\t\tif (apiKey != null) {\n\t\t\tconfig.setApiKey(apiKey);\n\t\t}\n\t\treturn this;\n\t}\n\n\t/**","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/chinabugotech/hutool/blob/8870454b2a0c29cc6ffd31dcf5667c8ceb2fc442/hutool-ai/src/main/java/cn/hutool/ai/core/AIConfigBuilder.java#L31-L67","documentation":"A broad catch-all RuntimeException wrapping ANY exception thrown inside the AIConfigBuilder constructor. Note it also masks the inner 'Unsupported model' IllegalArgumentException from error 2: that throw is caught here and re-wrapped, so callers see 'Failed to create AIConfig instance' with the real reason on getCause(). Other wrapped causes include NoSuchMethodException (config class has no no-arg constructor), InstantiationException, IllegalAccessException, or InvocationTargetException (constructor threw).","triggerScenarios":"Any failure constructing the config: unsupported vendor name (inner IllegalArgumentException), the located AIConfig class lacks a public no-arg constructor, the no-arg constructor itself throws, or a security manager blocks reflective access.","commonSituations":"Calling AIConfigBuilder with an unregistered vendor; a custom AIConfig whose only constructor takes arguments; module/JPMS or security restrictions blocking setAccessible; upgrading hutool where a config class constructor changed.","solutions":["Inspect ex.getCause() / getCause().getMessage() to find the real failure (often the 'Unsupported model' IllegalArgumentException).","Pass a supported ModelName vendor string.","Ensure any custom AIConfig implementation declares a public no-arg constructor.","If on JPMS, open the package containing the AIConfig implementation to hutool-ai for reflective instantiation."],"exampleFix":"// before\ntry {\n    new AIConfigBuilder(\"claude\");\n} catch (RuntimeException e) {\n    // e.getMessage() == \"Failed to create AIConfig instance\" -- real reason hidden\n}\n\n// after\ntry {\n    new AIConfigBuilder(ModelName.OPENAI.getValue());\n} catch (RuntimeException e) {\n    Throwable root = e.getCause() != null ? e.getCause() : e;\n    log.error(\"config build failed: {}\", root.getMessage(), root);\n}","handlingStrategy":"try-catch","validationCode":"// Pre-flight: registry lookup + no-arg constructor presence\nClass<? extends AIConfig> clazz = AIConfigRegistry.getConfigClass(vendor);\nif (clazz == null) throw new IllegalStateException(\"unsupported vendor \" + vendor);\ntry {\n    clazz.getDeclaredConstructor();\n} catch (NoSuchMethodException nsme) {\n    throw new IllegalStateException(clazz + \" has no no-arg constructor\", nsme);\n}","typeGuard":null,"tryCatchPattern":"try {\n    return new AIConfigBuilder(vendor);\n} catch (RuntimeException e) {\n    Throwable root = e.getCause() != null ? e.getCause() : e;\n    // root may be: IllegalArgumentException(unsupported), NoSuchMethodException,\n    // InstantiationException, IllegalAccessException, InvocationTargetException\n    log.error(\"AIConfig build failed: {}\", root.toString(), root);\n    throw e;\n}","preventionTips":["Always log getCause() -- the wrapper hides the real reason.","Keep custom AIConfig implementations with a public no-arg constructor.","On JPMS, open the config package to hutool-ai for reflection."],"tags":["reflection","spi","error-masking","builder"],"backgroundTag":null,"analyzedSha":"8870454b2a0c29cc6ffd31dcf5667c8ceb2fc442","analyzedAt":"2026-08-14T04:01:12.892Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}