alibaba/spring-cloud-alibaba · critical · IllegalStateException

Binder not available in BootstrapContext

Error message

Binder not available in BootstrapContext

What it means

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.

Source

Thrown at spring-cloud-alibaba-starters/spring-alibaba-nacos-config/src/main/java/com/alibaba/cloud/nacos/configdata/NacosConfigDataLoader.java:132

	private Option[] getOptions(ConfigDataLoaderContext context,
			NacosConfigDataResource resource) {
		List<Option> options = new ArrayList<>();
		options.add(Option.IGNORE_IMPORTS);
		options.add(Option.IGNORE_PROFILES);
		if (getPreference(context, resource) == REMOTE) {
			// mark it as 'PROFILE_SPECIFIC' config, it has higher priority,
			// will override the none profile specific config.
			// fixed https://github.com/alibaba/spring-cloud-alibaba/issues/2455
			options.add(Option.PROFILE_SPECIFIC);
		}
		return options.toArray(new Option[0]);
	}

	private ConfigPreference getPreference(ConfigDataLoaderContext context,
			NacosConfigDataResource resource) {
		Binder binder = context.getBootstrapContext().get(Binder.class);
		if (binder == null) {
			throw new IllegalStateException("Binder not available in BootstrapContext");
		}
		String prefix = NacosPropertiesPrefixer.getPrefix(binder);


		ConfigPreference preference = binder
				.bind(prefix + ".config.preference", ConfigPreference.class)
				.orElse(LOCAL);
		String specificPreference = resource.getConfig().getPreference();
		if (specificPreference != null) {
			try {
				preference = ConfigPreference.valueOf(specificPreference.toUpperCase(Locale.ROOT));
			}
			catch (IllegalArgumentException ignore) {
				// illegal preference value, just ignore.
				log.error(String.format(
						"illegal preference value: %s, using default preference: %s",
						specificPreference, preference));
			}

View on GitHub (pinned to 115d590110)

Solutions

1. Use a compatible Spring Boot version for your spring-cloud-alibaba release (check the compatibility matrix).
2. Avoid replacing the bootstrap context or the default Binder registration.
3. If invoking NacosConfigDataLoader in tests, populate the bootstrap context with a Binder before load().
4. Search for overrides of the config-data bootstrap setup that drop Binder.

Example fix

// before (test invokes loader with empty bootstrap context)
ConfigData data = loader.doLoad(context, resource); // -> IllegalStateException
// after
Binder binder = Binder.get(environment);
context.getBootstrapContext().registerIfAbsent(Binder.class, InstanceSupplier.of(binder));
ConfigData data = loader.doLoad(context, resource);

// In tests invoking the loader, register a Binder in the bootstrap context first.
Binder binder = Binder.get(environment);
bootstrapContext.registerIfAbsent(Binder.class, BootstrapRegistry.InstanceSupplier.of(binder));

When it happens

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

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

Related errors

• NacosConfigManager not available
• NacosConfigProperties not available
• NacosConfigProperties could not be loaded
• dataId must be specified
• illegal URI: {uris}

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