chinabugotech/hutool · error · RuntimeException

Failed to create AIConfig instance

Error message

Failed to create AIConfig instance

What it means

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).

Source

Thrown at hutool-ai/src/main/java/cn/hutool/ai/core/AIConfigBuilder.java:49

	/**
	 * 构造
	 *
	 * @param modelName 模型厂商的名称（注意不是指具体的模型）
	 */
	public AIConfigBuilder(final String modelName) {
		try {
			// 获取配置类
			final Class<? extends AIConfig> configClass = AIConfigRegistry.getConfigClass(modelName);
			if (configClass == null) {
				throw new IllegalArgumentException("Unsupported model: " + modelName);
			}

			// 使用反射创建实例
			final Constructor<? extends AIConfig> constructor = configClass.getDeclaredConstructor();
			config = constructor.newInstance();
		} catch (final Exception e) {
			throw new RuntimeException("Failed to create AIConfig instance", e);
		}
	}

	/**
	 * 设置apiKey
	 *
	 * @param apiKey apiKey
	 * @return config
	 * @since 5.8.38
	 */
	public synchronized AIConfigBuilder setApiKey(final String apiKey) {
		if (apiKey != null) {
			config.setApiKey(apiKey);
		}
		return this;
	}

	/**

View on GitHub (pinned to 8870454b2a)

Solutions

1. Inspect ex.getCause() / getCause().getMessage() to find the real failure (often the 'Unsupported model' IllegalArgumentException).
2. Pass a supported ModelName vendor string.
3. Ensure any custom AIConfig implementation declares a public no-arg constructor.
4. If on JPMS, open the package containing the AIConfig implementation to hutool-ai for reflective instantiation.

Example fix

// before
try {
    new AIConfigBuilder("claude");
} catch (RuntimeException e) {
    // e.getMessage() == "Failed to create AIConfig instance" -- real reason hidden
}

// after
try {
    new AIConfigBuilder(ModelName.OPENAI.getValue());
} catch (RuntimeException e) {
    Throwable root = e.getCause() != null ? e.getCause() : e;
    log.error("config build failed: {}", root.getMessage(), root);
}

// Pre-flight: registry lookup + no-arg constructor presence
Class<? extends AIConfig> clazz = AIConfigRegistry.getConfigClass(vendor);
if (clazz == null) throw new IllegalStateException("unsupported vendor " + vendor);
try {
    clazz.getDeclaredConstructor();
} catch (NoSuchMethodException nsme) {
    throw new IllegalStateException(clazz + " has no no-arg constructor", nsme);
}

try {
    return new AIConfigBuilder(vendor);
} catch (RuntimeException e) {
    Throwable root = e.getCause() != null ? e.getCause() : e;
    // root may be: IllegalArgumentException(unsupported), NoSuchMethodException,
    // InstantiationException, IllegalAccessException, InvocationTargetException
    log.error("AIConfig build failed: {}", root.toString(), root);
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unsupported model:
• Unsupported model:
• Upload failed
• Failed to download media from URL:
• Failed to get remote file MIME type

AI-assisted analysis of chinabugotech/hutool@8870454b2a (2026-08-14). Data as JSON: /api/errors/5dafcf96f561a1c8. Report an issue: GitHub.