spring-projects/spring-security · error · IllegalArgumentException

Failed to parse address 'X'

Error message

Failed to parse address 'X'

What it means

InetAddressParser.parseAddress converts a literal IP string to InetAddress; on UnknownHostException it wraps the failure in IllegalArgumentException('Failed to parse address X'). Before parsing it asserts the input looks like an IP literal (assertNotHostName), so hostnames are rejected earlier with a different message; this error means the string was IP-shaped but still unresolvable/malformed (e.g., bad octets, malformed IPv6).

Source

Thrown at core/src/main/java/org/springframework/security/util/matcher/InetAddressParser.java:51

 */
final class InetAddressParser {

	private static Pattern IPV4 = Pattern.compile("^\\d{1,3}(?:\\.\\d{1,3}){0,3}(?:/\\d{1,2})?$");

	/**
	 * Parses the given address string into an {@link InetAddress}.
	 * @param address the IP address string to parse
	 * @return the parsed {@link InetAddress}
	 * @throws IllegalArgumentException if the address cannot be parsed or appears to be a
	 * hostname
	 */
	static InetAddress parseAddress(String address) {
		assertNotHostName(address);
		try {
			return InetAddress.getByName(address);
		}
		catch (UnknownHostException ex) {
			throw new IllegalArgumentException("Failed to parse address '" + address + "'", ex);
		}
	}

	static void assertNotHostName(String ipAddress) {
		Assert.isTrue(isIpAddress(ipAddress),
				() -> String.format("ipAddress %s doesn't look like an IP Address. Is it a host name?", ipAddress));
	}

	private static boolean isIpAddress(String ipAddress) {
		if (!org.springframework.util.StringUtils.hasText(ipAddress)) {
			return false;
		}
		// @formatter:off
		return IPV4.matcher(ipAddress).matches()
			|| ipAddress.charAt(0) == '['
			|| ipAddress.charAt(0) == ':'
			|| Character.digit(ipAddress.charAt(0), 16) != -1
			&& ipAddress.indexOf(':') > 0;

View on GitHub (pinned to 96852e8860)

Solutions

1. Correct the address literal; validate with java.net.InetAddress.getByName in a config test or use InetAddressValidator before wiring the matcher
2. Use CIDR form with IpAddressMatcher only if intended ('192.168.0.0/24') — ensure you are not mixing CIDR with plain-address parsing
3. For hostnames, resolve them yourself first and configure the resulting IP, or use a matcher that accepts hostnames
4. Strip whitespace and surrounding quotes from configuration values

Example fix

// before
new IpAddressMatcher("10.0.0.256"); // IllegalArgumentException
// after
new IpAddressMatcher("10.0.0.1"); // or "10.0.0.0/24" for ranges

try {
    InetAddress.getByName(address.trim());
} catch (UnknownHostException e) {
    throw new IllegalArgumentException("Not a valid IP literal: " + address, e);
}

static boolean isIpLiteral(String s) {
    return s != null && java.util.regex.Pattern
        .matches("^([0-9]{1,3}\\.){3}[0-9]{1,3}$|^[0-9a-fA-F:]+$", s.trim());
}

try {
    matcher = new IpAddressMatcher(address);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Failed to parse address")) {
        // fall back to a permissive/default matcher and log config problem
    } else { throw e; }
}

When it happens

Trigger: Configuring an IpAddressMatcher / RequestMatcherInfrastructure with a malformed IPv4 string (e.g., '999.1.1.1', '10.0.0.256') or malformed IPv6 ('::zz', truncated); passing empty or whitespace-containing strings that still pass the IP-shape heuristic.

Common situations: Typos in firewall/allowlist configuration properties; copy-pasting hostnames that partially look like IPs; IPv6 addresses written with unsupported shorthand or zone indices; environment-specific config where CIDR strings are passed where a plain address is expected.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Can not set rememberMeCookieName and custom rememberMeServic
• Failed to parse address 'X'
• metadataResolver must be an IterableMetadataSource or have a
• Unsupported implementation of Sid
• Cannot pass null or empty values to constructor

AI-assisted analysis of spring-projects/spring-security@96852e8860 (2026-09-10). Data as JSON: /api/errors/075b30ea8115a0ea. Report an issue: GitHub.