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

Make get() return a concrete Locale (e.g. Locale.getDefault() or Locale.ROOT) instead of null.

junit-team/junit5 · error · ExtensionConfigurationException

LocaleProvider instance returned with null

Error message

LocaleProvider instance returned with null

What it means

ExtensionConfigurationException from DefaultLocaleExtension.invoke, thrown when the configured LocaleProvider.get() returns null. A provider must return a non-null Locale; null is treated as a configuration defect rather than a meaningful value.

Solutions

Make get() return a concrete Locale (e.g. Locale.getDefault() or Locale.ROOT) instead of null.
Guard the lookup inside get(): Optional.ofNullable(...).orElse(Locale.ROOT).

Example fix

// before
public Locale get() { return readFromEnv(); } // returns null when unset
// after
public Locale get() {
    return Optional.ofNullable(readFromEnv()).orElse(Locale.ROOT);
}

Defensive patterns

Strategy: validation

Validate before calling

Locale l = provider.get();
if (l == null) throw new IllegalStateException("provider returned null");

Prevention

LocaleProvider.get() must never return null.
Fallback to Locale.ROOT or Locale.getDefault() inside get().
Unit-test the provider independently before wiring it into the extension.

When it happens

Trigger: Specifying @DefaultLocale(localeProvider = MyProvider.class) where MyProvider.get() returns null — e.g. a lookup that yielded no result and returned null instead of a default.

Common situations: Provider that reads Locale from an env var or system property that is unset; a provider that returns null 'to mean default'; copy of a stub provider that was never finished.

Related errors

AI-assisted analysis of junit-team/junit5@f070c699a0 (2026-08-11). Data as JSON: /api/errors/2fb32aa27b84d0d4. Report an issue: GitHub.

Appendix: 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 f070c699a0)