{"record":{"id":"075b30ea8115a0ea","repo":"spring-projects/spring-security","slug":"failed-to-parse-address-x","errorCode":null,"errorMessage":"Failed to parse address 'X'","messagePattern":"Failed to parse address 'X'","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/springframework/security/util/matcher/InetAddressParser.java","lineNumber":51,"sourceCode":" */\nfinal class InetAddressParser {\n\n\tprivate static Pattern IPV4 = Pattern.compile(\"^\\\\d{1,3}(?:\\\\.\\\\d{1,3}){0,3}(?:/\\\\d{1,2})?$\");\n\n\t/**\n\t * Parses the given address string into an {@link InetAddress}.\n\t * @param address the IP address string to parse\n\t * @return the parsed {@link InetAddress}\n\t * @throws IllegalArgumentException if the address cannot be parsed or appears to be a\n\t * hostname\n\t */\n\tstatic InetAddress parseAddress(String address) {\n\t\tassertNotHostName(address);\n\t\ttry {\n\t\t\treturn InetAddress.getByName(address);\n\t\t}\n\t\tcatch (UnknownHostException ex) {\n\t\t\tthrow new IllegalArgumentException(\"Failed to parse address '\" + address + \"'\", ex);\n\t\t}\n\t}\n\n\tstatic void assertNotHostName(String ipAddress) {\n\t\tAssert.isTrue(isIpAddress(ipAddress),\n\t\t\t\t() -> String.format(\"ipAddress %s doesn't look like an IP Address. Is it a host name?\", ipAddress));\n\t}\n\n\tprivate static boolean isIpAddress(String ipAddress) {\n\t\tif (!org.springframework.util.StringUtils.hasText(ipAddress)) {\n\t\t\treturn false;\n\t\t}\n\t\t// @formatter:off\n\t\treturn IPV4.matcher(ipAddress).matches()\n\t\t\t|| ipAddress.charAt(0) == '['\n\t\t\t|| ipAddress.charAt(0) == ':'\n\t\t\t|| Character.digit(ipAddress.charAt(0), 16) != -1\n\t\t\t&& ipAddress.indexOf(':') > 0;","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/spring-projects/spring-security/blob/96852e8860138a482cb13d1479573f24ff6443c6/core/src/main/java/org/springframework/security/util/matcher/InetAddressParser.java#L33-L69","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Correct the address literal; validate with java.net.InetAddress.getByName in a config test or use InetAddressValidator before wiring the matcher","Use CIDR form with IpAddressMatcher only if intended ('192.168.0.0/24') — ensure you are not mixing CIDR with plain-address parsing","For hostnames, resolve them yourself first and configure the resulting IP, or use a matcher that accepts hostnames","Strip whitespace and surrounding quotes from configuration values"],"exampleFix":"// before\nnew IpAddressMatcher(\"10.0.0.256\"); // IllegalArgumentException\n// after\nnew IpAddressMatcher(\"10.0.0.1\"); // or \"10.0.0.0/24\" for ranges","handlingStrategy":"validation","validationCode":"try {\n    InetAddress.getByName(address.trim());\n} catch (UnknownHostException e) {\n    throw new IllegalArgumentException(\"Not a valid IP literal: \" + address, e);\n}","typeGuard":"static boolean isIpLiteral(String s) {\n    return s != null && java.util.regex.Pattern\n        .matches(\"^([0-9]{1,3}\\\\.){3}[0-9]{1,3}$|^[0-9a-fA-F:]+$\", s.trim());\n}","tryCatchPattern":"try {\n    matcher = new IpAddressMatcher(address);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Failed to parse address\")) {\n        // fall back to a permissive/default matcher and log config problem\n    } else { throw e; }\n}","preventionTips":["Validate IP configuration values at startup (fail fast on typos)","Keep hostnames out of IP-literal settings, or resolve them explicitly first","Watch for out-of-range octets and malformed IPv6 in copy-pasted config","Trim whitespace/quotes from properties before building matchers"],"tags":["ip-address","parsing","illegal-argument","configuration"],"backgroundTag":"invalid-argument-format","analyzedSha":"96852e8860138a482cb13d1479573f24ff6443c6","analyzedAt":"2026-09-10T23:25:23.477Z","contentChangedAt":"2026-09-10T23:25:23.477Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}