What causes "Failed to convert value of type '{}' to required type '{}'" in spring-projects/spring-framework?

Fix the source value so it parses cleanly into the target type.

spring-projects/spring-framework · error · TypeMismatchException

typeMismatch

typeMismatch

Error message

Failed to convert value of type '{}' to required type '{}'

What it means

TypeMismatchException raised by TypeConverterSupport when the delegate throws ConversionException or IllegalArgumentException (e.g. error 185). Unlike error 187, a converter/editor was found and ran but produced an invalid value or threw during conversion. Code 'typeMismatch' is the conventional error code used by Spring's binding/validation pipeline.

Source

Thrown at spring-beans/src/main/java/org/springframework/beans/TypeConverterSupport.java:82

	public <T> @Nullable T convertIfNecessary(@Nullable Object value, @Nullable Class<T> requiredType,
			@Nullable TypeDescriptor typeDescriptor) throws TypeMismatchException {

		return convertIfNecessary(null, value, requiredType, typeDescriptor);
	}

	private <T> @Nullable T convertIfNecessary(@Nullable String propertyName, @Nullable Object value,
			@Nullable Class<T> requiredType, @Nullable TypeDescriptor typeDescriptor) throws TypeMismatchException {

		Assert.state(this.typeConverterDelegate != null, "No TypeConverterDelegate");
		try {
			return this.typeConverterDelegate.convertIfNecessary(
					propertyName, null, value, requiredType, typeDescriptor);
		}
		catch (ConverterNotFoundException | IllegalStateException ex) {
			throw new ConversionNotSupportedException(value, requiredType, ex);
		}
		catch (ConversionException | IllegalArgumentException ex) {
			throw new TypeMismatchException(value, requiredType, ex);
		}
	}

}

View on GitHub (pinned to 69bf83ad71)

Solutions

Fix the source value so it parses cleanly into the target type.
Register or fix the Converter/PropertyEditor so it does not throw on the input.
Make the injection point optional (e.g. wrap in Optional<>) or handle the binding error in a @ExceptionHandler / @InitBinder.
Loosen the target type if the input range is wider than expected.

Example fix

// before
@Value("${threads}") int threads; // property value "unlimited" -> TypeMismatchException

// after
@Value("${threads:4}") int threads; // default to 4 when unparsable/missing

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate the source string parses before binding to a strict type
if (requiredType == int.class && !StringUtils.isNumeric(raw)) {
    throw new IllegalArgumentException("value '" + raw + "' is not numeric");
}

Try / catch

try {
    wrapper.setPropertyValue("count", raw);
} catch (TypeMismatchException ex) {
    // conversion ran but produced/failed value; log and surface field-level error
    errors.rejectValue("count", "typeMismatch");
}

Prevention

Provide defaults for @Value/properties so unparseable inputs fall back cleanly.
Validate raw inputs at the controller boundary before binding.
Register @ExceptionHandler(MethodArgumentTypeMismatchException) in web layers.

When it happens

Trigger: Binding "abc" to an int field (NumberFormatException wrapped as IllegalArgumentException -> TypeMismatchException at line 82); a Converter throwing a ConversionException; a PropertyEditor returning a value that fails a later check.

Common situations: Form binding / @RequestParam with a non-numeric value for a numeric field; @Value("${x}") where the property string cannot be parsed to the injection type; SpEL conversion failures.

Related errors

AI-assisted analysis of spring-projects/spring-framework@69bf83ad71 (2026-08-09). Data as JSON: /api/errors/a60571f12ac0f00f. Report an issue: GitHub.