{"record":{"id":"31724147236dc591","repo":"alibaba/spring-cloud-alibaba","slug":"binder-not-available-in-bootstrapcontext","errorCode":null,"errorMessage":"Binder not available in BootstrapContext","messagePattern":"Binder not available in BootstrapContext","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"spring-cloud-alibaba-starters/spring-alibaba-nacos-config/src/main/java/com/alibaba/cloud/nacos/configdata/NacosConfigDataLoader.java","lineNumber":132,"sourceCode":"\tprivate Option[] getOptions(ConfigDataLoaderContext context,\n\t\t\tNacosConfigDataResource resource) {\n\t\tList<Option> options = new ArrayList<>();\n\t\toptions.add(Option.IGNORE_IMPORTS);\n\t\toptions.add(Option.IGNORE_PROFILES);\n\t\tif (getPreference(context, resource) == REMOTE) {\n\t\t\t// mark it as 'PROFILE_SPECIFIC' config, it has higher priority,\n\t\t\t// will override the none profile specific config.\n\t\t\t// fixed https://github.com/alibaba/spring-cloud-alibaba/issues/2455\n\t\t\toptions.add(Option.PROFILE_SPECIFIC);\n\t\t}\n\t\treturn options.toArray(new Option[0]);\n\t}\n\n\tprivate ConfigPreference getPreference(ConfigDataLoaderContext context,\n\t\t\tNacosConfigDataResource resource) {\n\t\tBinder binder = context.getBootstrapContext().get(Binder.class);\n\t\tif (binder == null) {\n\t\t\tthrow new IllegalStateException(\"Binder not available in BootstrapContext\");\n\t\t}\n\t\tString prefix = NacosPropertiesPrefixer.getPrefix(binder);\n\n\n\t\tConfigPreference preference = binder\n\t\t\t\t.bind(prefix + \".config.preference\", ConfigPreference.class)\n\t\t\t\t.orElse(LOCAL);\n\t\tString specificPreference = resource.getConfig().getPreference();\n\t\tif (specificPreference != null) {\n\t\t\ttry {\n\t\t\t\tpreference = ConfigPreference.valueOf(specificPreference.toUpperCase(Locale.ROOT));\n\t\t\t}\n\t\t\tcatch (IllegalArgumentException ignore) {\n\t\t\t\t// illegal preference value, just ignore.\n\t\t\t\tlog.error(String.format(\n\t\t\t\t\t\t\"illegal preference value: %s, using default preference: %s\",\n\t\t\t\t\t\tspecificPreference, preference));\n\t\t\t}","sourceCodeStart":114,"sourceCodeEnd":150,"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/configdata/NacosConfigDataLoader.java#L114-L150","documentation":"Thrown by NacosConfigDataLoader.getPreference when context.getBootstrapContext().get(Binder.class) returns null. The Binder is needed to read spring.cloud.nacos.config.preference and the prefix options. A null Binder in the bootstrap context indicates an unexpected Spring Boot config-data lifecycle state where the Binder was not published to the bootstrap registry before the loader's preference resolution.","triggerScenarios":"doLoad reaches getPreference() while the bootstrap context has no Binder registered. Typically a Spring Boot version incompatibility or a customized/overridden bootstrap context that did not register Binder, or calling the loader outside the standard config-data pipeline.","commonSituations":"Upgrading Spring Boot across a version where Binder registration in the bootstrap context changed; a custom ConfigDataLoader chain that replaces the standard bootstrap context; test harnesses invoking the loader directly without a populated context.","solutions":["Use a compatible Spring Boot version for your spring-cloud-alibaba release (check the compatibility matrix).","Avoid replacing the bootstrap context or the default Binder registration.","If invoking NacosConfigDataLoader in tests, populate the bootstrap context with a Binder before load().","Search for overrides of the config-data bootstrap setup that drop Binder."],"exampleFix":"// before (test invokes loader with empty bootstrap context)\nConfigData data = loader.doLoad(context, resource); // -> IllegalStateException\n// after\nBinder binder = Binder.get(environment);\ncontext.getBootstrapContext().registerIfAbsent(Binder.class, InstanceSupplier.of(binder));\nConfigData data = loader.doLoad(context, resource);","handlingStrategy":"validation","validationCode":"// In tests invoking the loader, register a Binder in the bootstrap context first.\nBinder binder = Binder.get(environment);\nbootstrapContext.registerIfAbsent(Binder.class, BootstrapRegistry.InstanceSupplier.of(binder));","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use the Spring Boot version your spring-cloud-alibaba release supports.","Do not replace the bootstrap context or default Binder registration.","Populate Binder when invoking NacosConfigDataLoader outside the standard pipeline."],"tags":["nacos","config-data","spring-boot","binder","version-compat"],"backgroundTag":null,"analyzedSha":"115d5901102009492e05d5ec18c3f79cad4077d0","analyzedAt":"2026-08-14T04:47:13.900Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}