{"record":{"id":"b9c06dcd1f3c92ea","repo":"alibaba/spring-cloud-alibaba","slug":"nacosconfiglistener-must-be-over-a-method-with","errorCode":null,"errorMessage":"@NacosConfigListener  must be over a method with  a single parameter","messagePattern":"@NacosConfigListener  must be over a method with  a single parameter","errorType":"validation","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"spring-cloud-alibaba-starters/spring-alibaba-nacos-config/src/main/java/com/alibaba/cloud/nacos/annotation/NacosAnnotationProcessor.java","lineNumber":331,"sourceCode":"\t\tfor (int i = 0; i < parameterTypes.length; i++) {\n\t\t\tsignature.append(parameterTypes[i].getSimpleName());\n\t\t\tif (i < parameterTypes.length - 1) {\n\t\t\t\tsignature.append(\", \");\n\t\t\t}\n\t\t}\n\n\t\tsignature.append(\")\");\n\t\treturn signature.toString();\n\t}\n\n\tprivate void handleMethodNacosConfigListener(NacosConfigListener annotation, String beanName, Object bean, Method method) {\n\t\tString dataId = annotation.dataId();\n\t\tString group = annotation.group();\n\t\tString key = annotation.key();\n\t\ttry {\n\t\t\tType[] parameterTypes = method.getGenericParameterTypes();\n\t\t\tif (parameterTypes.length != 1) {\n\t\t\t\tthrow new RuntimeException(\n\t\t\t\t\t\t\"@NacosConfigListener  must be over a method with  a single parameter\");\n\t\t\t}\n\n\t\t\tString configInfo = getGroupKeyContent(dataId, group, true);\n\t\t\tString refreshTargetKey = beanName + \"#method#\" + methodSignature(method);\n\t\t\tTargetRefreshable currentTarget = targetListenerMap.get(refreshTargetKey);\n\t\t\tif (currentTarget != null) {\n\t\t\t\tlog.info(\"[Nacos Config] reset {} listener from  {} to {} \", refreshTargetKey,\n\t\t\t\t\t\tcurrentTarget.getTarget(), bean);\n\t\t\t\tcurrentTarget.setTarget(bean);\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tlog.info(\"[Nacos Config] register {} listener on {} \", refreshTargetKey,\n\t\t\t\t\tbean);\n\n\t\t\tTargetRefreshable listener = null;\n\t\t\tif (org.springframework.util.StringUtils.hasText(key)) {","sourceCodeStart":313,"sourceCodeEnd":349,"githubUrl":"https://github.com/alibaba/spring-cloud-alibaba/blob/115d5901102009492e05d5ec18c3f79cad4077d0/spring-cloud-alibaba-starters/spring-alibaba-nacos-config/src/main/java/com/alibaba/cloud/nacos/annotation/NacosAnnotationProcessor.java#L313-L349","documentation":"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.","triggerScenarios":"Annotating a no-arg method or a multi-arg method with @NacosConfigListener. Surfaces during Spring context refresh when the processor inspects annotated beans.","commonSituations":"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.","solutions":["Ensure the @NacosConfigListener method has exactly one parameter (e.g., void onConfig(String config) or your bound type).","Inject collaborators via fields/constructor, not listener-method parameters.","Remove the annotation from methods that cannot conform."],"exampleFix":"// before\n@NacosConfigListener(dataId = \"app.properties\")\npublic void onConfig(String content, MyService svc) { ... }\n// after\n@Autowired private MyService svc;\n@NacosConfigListener(dataId = \"app.properties\")\npublic void onConfig(String content) { ... }","handlingStrategy":"validation","validationCode":"// Assert every @NacosConfigListener method has exactly one parameter.\nfor (Method m : bean.getClass().getMethods()) {\n    if (m.isAnnotationPresent(NacosConfigListener.class) && m.getParameterCount() != 1) {\n        throw new IllegalStateException(\"@NacosConfigListener must be single-param: \" + m);\n    }\n}","typeGuard":"static boolean isConfigListenerShape(java.lang.reflect.Method m) {\n    return m.getParameterCount() == 1;\n}","tryCatchPattern":null,"preventionTips":["Inject collaborators via fields, not listener parameters.","Keep @NacosConfigListener methods single-arg.","Add a startup assertion to catch signature drift."],"tags":["nacos","config","annotation","reflection","contract-violation"],"backgroundTag":null,"analyzedSha":"115d5901102009492e05d5ec18c3f79cad4077d0","analyzedAt":"2026-08-14T04:47:13.900Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}