alibaba/spring-cloud-alibaba · error · RuntimeException

@NacosConfigListener must be over a method with a single p

Error message

@NacosConfigListener  must be over a method with  a single parameter

What it means

Thrown by NacosAnnotationProcessor.handleMethodNacosConfigListener when a method annotated with @NacosConfigListener has any number of parameters other than exactly one. The processor reads method.getGenericParameterTypes() and rejects methods whose parameter count is not 1, with a RuntimeException at bean-post-processing time. The single parameter's type is bound to the config content/key, so the contract requires exactly one argument.

Source

Thrown at spring-cloud-alibaba-starters/spring-alibaba-nacos-config/src/main/java/com/alibaba/cloud/nacos/annotation/NacosAnnotationProcessor.java:331

		for (int i = 0; i < parameterTypes.length; i++) {
			signature.append(parameterTypes[i].getSimpleName());
			if (i < parameterTypes.length - 1) {
				signature.append(", ");
			}
		}

		signature.append(")");
		return signature.toString();
	}

	private void handleMethodNacosConfigListener(NacosConfigListener annotation, String beanName, Object bean, Method method) {
		String dataId = annotation.dataId();
		String group = annotation.group();
		String key = annotation.key();
		try {
			Type[] parameterTypes = method.getGenericParameterTypes();
			if (parameterTypes.length != 1) {
				throw new RuntimeException(
						"@NacosConfigListener  must be over a method with  a single parameter");
			}

			String configInfo = getGroupKeyContent(dataId, group, true);
			String refreshTargetKey = beanName + "#method#" + methodSignature(method);
			TargetRefreshable currentTarget = targetListenerMap.get(refreshTargetKey);
			if (currentTarget != null) {
				log.info("[Nacos Config] reset {} listener from  {} to {} ", refreshTargetKey,
						currentTarget.getTarget(), bean);
				currentTarget.setTarget(bean);
				return;
			}

			log.info("[Nacos Config] register {} listener on {} ", refreshTargetKey,
					bean);

			TargetRefreshable listener = null;
			if (org.springframework.util.StringUtils.hasText(key)) {

View on GitHub (pinned to 115d590110)

Solutions

1. Ensure the @NacosConfigListener method has exactly one parameter (e.g., void onConfig(String config) or your bound type).
2. Inject collaborators via fields/constructor, not listener-method parameters.
3. Remove the annotation from methods that cannot conform.

Example fix

// before
@NacosConfigListener(dataId = "app.properties")
public void onConfig(String content, MyService svc) { ... }
// after
@Autowired private MyService svc;
@NacosConfigListener(dataId = "app.properties")
public void onConfig(String content) { ... }

// Assert every @NacosConfigListener method has exactly one parameter.
for (Method m : bean.getClass().getMethods()) {
    if (m.isAnnotationPresent(NacosConfigListener.class) && m.getParameterCount() != 1) {
        throw new IllegalStateException("@NacosConfigListener must be single-param: " + m);
    }
}

static boolean isConfigListenerShape(java.lang.reflect.Method m) {
    return m.getParameterCount() == 1;
}

When it happens

Trigger: Annotating a no-arg method or a multi-arg method with @NacosConfigListener. Surfaces during Spring context refresh when the processor inspects annotated beans.

Common situations: Migrating from another config-listener API that allowed extra params; writing a listener that also injects a collaborator via parameters (Spring won't inject here); refactoring that adds/removes a parameter.

Related errors

• NacosConfigKeysChangeListener must be marked as a single par
• ConfigService is not initialized
• Invalid date format
• ApplicationContext not set
• 4000

AI-assisted analysis of alibaba/spring-cloud-alibaba@115d590110 (2026-08-14). Data as JSON: /api/errors/b9c06dcd1f3c92ea. Report an issue: GitHub.