alibaba/spring-cloud-alibaba · error · RuntimeException

NacosConfigKeysChangeListener must be marked as a single par

Error message

NacosConfigKeysChangeListener must be marked as a single parameter with ConfigChangeEvent

What it means

Thrown by NacosAnnotationProcessor.handleMethodNacosConfigKeysChangeListener when a method annotated with @NacosConfigKeysChangeListener does not have exactly one parameter, or that parameter is not assignable to com.alibaba.nacos.api.config.listener.ConfigChangeEvent. The processor inspects method.getParameterTypes() at bean-post-processing time and rejects mis-shaped listener methods with a RuntimeException. This is a usage-contract violation, not a runtime data error.

Source

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

			getNacosConfigManager().getConfigService()
					.addListener(dataId, group, listener);
			targetListenerMap.put(refreshTargetKey, listener);

		}
		catch (Exception e) {
			throw new RuntimeException(e);
		}
	}

	private void handleMethodNacosConfigKeysChangeListener(NacosConfigKeysListener annotation, String beanName, Object bean,
			Method method) {
		String dataId = annotation.dataId();
		String group = annotation.group();
		try {
			Class<?>[] parameterTypes = method.getParameterTypes();
			if (parameterTypes.length != 1 || !ConfigChangeEvent.class.isAssignableFrom(parameterTypes[0])) {
				throw new RuntimeException(
						"NacosConfigKeysChangeListener must be marked as a single parameter with ConfigChangeEvent");
			}

			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);
			// annotation on string.
			NacosPropertiesKeyListener nacosPropertiesKeyListener = new NacosPropertiesKeyListener(bean, wrapArrayToSet(annotation.interestedKeys()),
					wrapArrayToSet(annotation.interestedKeyPrefixes())) {

View on GitHub (pinned to 115d590110)

Solutions

1. Give the annotated method exactly one parameter of type ConfigChangeEvent: void onChange(ConfigChangeEvent event).
2. Remove @NacosConfigKeysChangeListener from methods that cannot match the contract.
3. Rebuild/restart so the processor re-validates signatures after the fix.

Example fix

// before
@NacosConfigKeysChangeListener(dataId = "app.yml")
public void onChange(String content) { ... }
// after
@NacosConfigKeysChangeListener(dataId = "app.yml")
public void onChange(ConfigChangeEvent event) { ... }

// At startup, assert every @NacosConfigKeysChangeListener method has one ConfigChangeEvent param.
for (Method m : bean.getClass().getMethods()) {
    if (m.isAnnotationPresent(NacosConfigKeysChangeListener.class)) {
        Class<?>[] p = m.getParameterTypes();
        if (p.length != 1 || !ConfigChangeEvent.class.isAssignableFrom(p[0])) {
            throw new IllegalStateException("bad listener signature: " + m);
        }
    }
}

static boolean isKeysChangeListenerShape(java.lang.reflect.Method m) {
    Class<?>[] p = m.getParameterTypes();
    return p.length == 1 && ConfigChangeEvent.class.isAssignableFrom(p[0]);
}

When it happens

Trigger: Annotating a no-arg method, a multi-arg method, or a method whose single argument is not ConfigChangeEvent with @NacosConfigKeysChangeListener. The error surfaces during Spring context refresh when the annotation processor scans beans.

Common situations: Copying an example but giving the listener a different signature (e.g., a String or a custom DTO); refactoring a method and dropping the event parameter; misunderstanding the required signature from docs.

Related errors

• @NacosConfigListener must be over a method with a single p
• 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/5814344043106d06. Report an issue: GitHub.