{"record":{"id":"63e50d1fbc8ad5e5","repo":"spring-projects/spring-security","slug":"failed-to-parse-address-x-63e50d","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/IpInetAddressMatcher.java","lineNumber":83,"sourceCode":"\t\t\tnMaskBits = -1;\n\t\t}\n\t\tthis.requiredAddress = InetAddressParser.parseAddress(requiredAddress);\n\t\tthis.nMaskBits = nMaskBits;\n\t\tAssert.isTrue(this.requiredAddress.getAddress().length * 8 >= this.nMaskBits, () -> String\n\t\t\t.format(\"IP address %s is too short for bitmask of length %d\", requiredAddress, this.nMaskBits));\n\t}\n\n\tprivate static InetAddress parse(String address) {\n\t\ttry {\n\t\t\tInetAddress result = InetAddress.getByName(address);\n\t\t\tif (address.matches(\".*[a-zA-Z\\\\-].*$\") && !address.contains(\":\")) {\n\t\t\t\tlogger.warn(\"Hostname '\" + address + \"' resolved to \" + result.toString()\n\t\t\t\t\t\t+ \" will be used on IP address matching\");\n\t\t\t}\n\t\t\treturn result;\n\t\t}\n\t\tcatch (UnknownHostException ex) {\n\t\t\tthrow new IllegalArgumentException(String.format(\"Failed to parse address '%s'\", address), ex);\n\t\t}\n\t}\n\n\t@Override\n\tpublic boolean matches(@Nullable InetAddress toCheck) {\n\t\tif (toCheck == null) {\n\t\t\treturn false;\n\t\t}\n\t\tif (this.nMaskBits < 0) {\n\t\t\treturn toCheck.equals(this.requiredAddress);\n\t\t}\n\t\tbyte[] remAddr = toCheck.getAddress();\n\t\tbyte[] reqAddr = this.requiredAddress.getAddress();\n\t\tint nMaskFullBytes = this.nMaskBits / 8;\n\t\tbyte finalByte = (byte) (0xFF00 >> (this.nMaskBits & 0x07));\n\t\tfor (int i = 0; i < nMaskFullBytes; i++) {\n\t\t\tif (remAddr[i] != reqAddr[i]) {\n\t\t\t\treturn false;","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/spring-projects/spring-security/blob/96852e8860138a482cb13d1479573f24ff6443c6/core/src/main/java/org/springframework/security/util/matcher/IpInetAddressMatcher.java#L65-L101","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a literal IP or valid CIDR ('192.168.1.0/24') instead of relying on DNS for the pattern","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","Validate the pattern with InetAddress.getByName(pattern) in a unit test before deploying","Check security configuration files for typos in the hasIpAddress value"],"exampleFix":"// before\nhttp.authorizeRequests().anyRequest().hasIpAddress(\"prod.internal/24\"); // unresolvable\n// after\nhttp.authorizeRequests().anyRequest().hasIpAddress(\"10.20.30.0/24\");","handlingStrategy":"validation","validationCode":"try {\n    InetAddress.getByName(pattern.contains(\"/\")\n        ? pattern.substring(0, pattern.indexOf('/')) : pattern);\n} catch (UnknownHostException e) {\n    throw new IllegalArgumentException(\"hasIpAddress pattern unresolvable: \" + pattern, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    IpInetAddressMatcher m = new IpInetAddressMatcher(pattern);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Failed to parse address\")) {\n        // correct the pattern or skip matcher registration; log loudly\n    } else { throw e; }\n}","preventionTips":["Prefer literal IPs/CIDR over DNS names in hasIpAddress and matcher config","Add a startup test that constructs every configured matcher","Ensure DNS for any hostnames used is available before bean creation","Double-check CIDR syntax and stray suffixes when copy-pasting patterns"],"tags":["ip-address","dns","matcher","configuration"],"backgroundTag":"invalid-argument-value","analyzedSha":"96852e8860138a482cb13d1479573f24ff6443c6","analyzedAt":"2026-09-10T23:25:23.477Z","contentChangedAt":"2026-09-10T23:25:23.477Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}