What causes "LocaleProvider instance returned with null" in junit-team/junit5?

Make get() never return null — fall back to Locale.getDefault() or a explicit default Locale.

junit-team/junit5 · error · ExtensionConfigurationException

LocaleProvider instance returned with null

Error message

LocaleProvider instance returned with null

What it means

Thrown as ExtensionConfigurationException by DefaultLocaleExtension.invoke when a successfully constructed LocaleProvider.get() returns null. The contract of LocaleProvider is to return a non-null Locale; null is treated as a programming error in the provider implementation.

Source

Thrown at junit-jupiter-api/src/main/java/org/junit/jupiter/api/util/DefaultLocaleExtension.java:122

			throw new ExtensionConfigurationException(
				"@DefaultLocale can only be used with a provider if value, language, country and variant are not set.");
		var providerClass = annotation.localeProvider();
		LocaleProvider provider;
		try {
			provider = ReflectionSupport.newInstance(providerClass);
		}
		catch (Exception exception) {
			throw new ExtensionConfigurationException(
				"LocaleProvider instance could not be constructed because of an exception", exception);
		}
		return invoke(provider);
	}

	@SuppressWarnings("ConstantValue")
	private static Locale invoke(LocaleProvider provider) {
		var locale = provider.get();
		if (locale == null) {
			throw new ExtensionConfigurationException("LocaleProvider instance returned with null");
		}
		return locale;
	}

	@Override
	public void afterEach(ExtensionContext context) {
		load(context, DEFAULT_KEY).ifPresent(Locale::setDefault);
	}

	private static void store(ExtensionContext context, String key, Locale value) {
		getStore(context).put(key, value);
	}

	private static Optional<Locale> load(ExtensionContext context, String key) {
		return Optional.ofNullable(getStore(context).get(key, Locale.class));
	}

	private static ExtensionContext.Store getStore(ExtensionContext context) {

View on GitHub (pinned to 956246301e)

Solutions

Make get() never return null — fall back to Locale.getDefault() or a explicit default Locale.
Use Optional.map(...).orElse(Locale.ROOT) instead of returning null.
Add a unit test that invokes get() in the no-input state to catch null returns early.

Example fix

// before
public Locale get() {
    return System.getenv("FORCE_LOCALE") == null
        ? null
        : Locale.forLanguageTag(System.getenv("FORCE_LOCALE"));
}

// after
public Locale get() {
    String tag = System.getenv("FORCE_LOCALE");
    return tag != null ? Locale.forLanguageTag(tag) : Locale.ROOT;
}

Defensive patterns

Strategy: validation

Validate before calling

LocaleProvider provider = ReflectionSupport.newInstance(MyLocaleProvider.class);
Locale result = provider.get();
java.util.Objects.requireNonNull(result, "LocaleProvider.get() must never return null");

Prevention

LocaleProvider.get() must never return null — fall back to Locale.ROOT or Locale.getDefault().
Use Optional.map(...).orElse(Locale.ROOT) instead of returning null from a lookup.
Add a unit test invoking get() with no input to catch null returns.

When it happens

Trigger: A LocaleProvider whose get() method returns null — e.g., it looks up a Locale from a map/env var that is absent and returns null instead of a default.

Common situations: Provider implementations that delegate to Optional.orElse(null) or Map.get on a possibly-absent key; providers that were not unit-tested for the absent-input case.

Related errors

AI-assisted analysis of junit-team/junit5@956246301e (2026-08-04). Data as JSON: /data/errors/2fb32aa27b84d0d4.json. Report an issue: GitHub.