spring-projects/spring-security · error · IllegalArgumentException

Failed to parse address 'X'

Error message

Failed to parse address 'X'

What it means

IpInetAddressMatcher.parse resolves the configured address (literal or hostname) to InetAddress; on UnknownHostException it throws IllegalArgumentException('Failed to parse address X'). This is the constructor-time conversion of the matcher's pattern, so an invalid pattern string means the matcher can never match and the whole bean creation fails.

Source

Thrown at core/src/main/java/org/springframework/security/util/matcher/IpInetAddressMatcher.java:83

			nMaskBits = -1;
		}
		this.requiredAddress = InetAddressParser.parseAddress(requiredAddress);
		this.nMaskBits = nMaskBits;
		Assert.isTrue(this.requiredAddress.getAddress().length * 8 >= this.nMaskBits, () -> String
			.format("IP address %s is too short for bitmask of length %d", requiredAddress, this.nMaskBits));
	}

	private static InetAddress parse(String address) {
		try {
			InetAddress result = InetAddress.getByName(address);
			if (address.matches(".*[a-zA-Z\\-].*$") && !address.contains(":")) {
				logger.warn("Hostname '" + address + "' resolved to " + result.toString()
						+ " will be used on IP address matching");
			}
			return result;
		}
		catch (UnknownHostException ex) {
			throw new IllegalArgumentException(String.format("Failed to parse address '%s'", address), ex);
		}
	}

	@Override
	public boolean matches(@Nullable InetAddress toCheck) {
		if (toCheck == null) {
			return false;
		}
		if (this.nMaskBits < 0) {
			return toCheck.equals(this.requiredAddress);
		}
		byte[] remAddr = toCheck.getAddress();
		byte[] reqAddr = this.requiredAddress.getAddress();
		int nMaskFullBytes = this.nMaskBits / 8;
		byte finalByte = (byte) (0xFF00 >> (this.nMaskBits & 0x07));
		for (int i = 0; i < nMaskFullBytes; i++) {
			if (remAddr[i] != reqAddr[i]) {
				return false;

View on GitHub (pinned to 96852e8860)

Solutions

1. Use a literal IP or valid CIDR ('192.168.1.0/24') instead of relying on DNS for the pattern
2. If a hostname is needed, ensure DNS resolves at startup (add to /etc/hosts or service discovery) and that it is not flagged as a hostname when literals are expected
3. Validate the pattern with InetAddress.getByName(pattern) in a unit test before deploying
4. Check security configuration files for typos in the hasIpAddress value

Example fix

// before
http.authorizeRequests().anyRequest().hasIpAddress("prod.internal/24"); // unresolvable
// after
http.authorizeRequests().anyRequest().hasIpAddress("10.20.30.0/24");

try {
    InetAddress.getByName(pattern.contains("/")
        ? pattern.substring(0, pattern.indexOf('/')) : pattern);
} catch (UnknownHostException e) {
    throw new IllegalArgumentException("hasIpAddress pattern unresolvable: " + pattern, e);
}

try {
    IpInetAddressMatcher m = new IpInetAddressMatcher(pattern);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Failed to parse address")) {
        // correct the pattern or skip matcher registration; log loudly
    } else { throw e; }
}

When it happens

Trigger: Constructing new IpInetAddressMatcher(pattern) with a string that is neither a valid IP literal nor resolvable hostname; DNS outage or missing DNS resolution making an otherwise-valid hostname unresolvable at startup; malformed IPv6 patterns or stray CIDR suffixes with wrong syntax.

Common situations: Spring Security authorizeRequests .hasIpAddress("...") configuration typos; containerized environments where a configured hostname is not in DNS yet at bean-creation time; copy-pasted patterns containing '/32' style suffixes combined with unresolvable names.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

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

Related errors

• Failed to parse address 'X'
• Hostname '%s' resolved to %s will be used on IP address matc
• Cannot apply {configurer} to already built object
• managerPassword is required if managerDn is supplied
• Embedded LDAP server is not provided

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