apache/shenyu · error · IllegalArgumentException

Invalid IPv6 format in Redis node URL: " + url

Error message

Invalid IPv6 format in Redis node URL: " + url

What it means

When a Redis node URL contains ']' (so it is treated as bracketed IPv6), it must start with '['. A URL like '192.168.1.1]' or '::1]' is malformed, and parseRedisNode() throws this IllegalArgumentException (note the message is built with string concatenation, so the thrown text is the concatenation result).

Solutions

1. Supply the full bracketed IPv6 form, e.g. '[::1]:6379'
2. Use a hostname or plain IPv4 like '127.0.0.1:6379' if IPv6 is not required
3. Escape/quote the value in YAML/properties so brackets are not stripped by the config parser

Example fix

// before
redis.nodes: ["::1]:6379"]
// after
redis.nodes: ["[::1]:6379"]

// validate before passing the node string
java.util.regex.Pattern NODE = Pattern.compile("^(\\[[0-9a-fA-F:.%]+\\])(:\\d{1,5})?$|^([^\\[\]]+)(:\\d{1,5})?$");
if (!NODE.matcher(nodeUrl.trim()).matches()) throw new IllegalArgumentException("Bad redis node: " + nodeUrl);

try {
    factory.create(List.of(nodeUrl));
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Invalid IPv6 format")) {
        logger.error("Fix bracketed IPv6 node URL: {}", nodeUrl, e);
    }
    throw e;
}

When it happens

Trigger: Passing a node string containing ']' that does not begin with '[', e.g. 'myhost]:6379' or a partially bracketed IPv6 '::1]:6379'.

Common situations: Hand-edited Redis cluster config where only one bracket of '[::1]:6379' survived; copy/paste from documentation dropping the opening bracket.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Redis node URL cannot be null or empty
• Port cannot be empty in Redis node URL: " + url
• Invalid port in Redis node URL: " + url
• Invalid format in Redis node URL: " + url
• Host is empty in Redis node URL: " + url

AI-assisted analysis of apache/shenyu@567142e072 (2026-09-12). Data as JSON: /api/errors/1eb96ade3ef3aa2e. Report an issue: GitHub.

Appendix: source

Thrown at shenyu-infra/shenyu-infra-redis/src/main/java/org/apache/shenyu/infra/redis/RedisConnectionFactory.java:150

            redisNodes.add(parseRedisNode(node));
        }
        return redisNodes;
    }

    private RedisNode parseRedisNode(final String url) {
        if (Objects.isNull(url) || url.trim().isEmpty()) {
            throw new IllegalArgumentException("Redis node URL cannot be null or empty");
        }
        
        String trimmedUrl = url.trim();
        String host = trimmedUrl;
        int port = 6379;
        int bracketIndex = trimmedUrl.lastIndexOf("]");
        
        if (bracketIndex > -1) {
            // IPv6 address format: [::1] or [::1]:6379
            if (!trimmedUrl.startsWith("[")) {
                throw new IllegalArgumentException("Invalid IPv6 format in Redis node URL: " + url);
            }
            int closingBracket = trimmedUrl.indexOf("]");
            if (closingBracket == -1 || closingBracket != bracketIndex) {
                throw new IllegalArgumentException("Invalid IPv6 format in Redis node URL: " + url);
            }
            
            // Extract IPv6 address (remove brackets)
            host = trimmedUrl.substring(1, closingBracket);
            
            // Check if port is specified after closing bracket
            if (closingBracket < trimmedUrl.length() - 1 && trimmedUrl.charAt(closingBracket + 1) == ':') {
                String portStr = trimmedUrl.substring(closingBracket + 2);
                if (portStr.isEmpty()) {
                    throw new IllegalArgumentException("Port cannot be empty in Redis node URL: " + url);
                }
                try {
                    port = Integer.parseInt(portStr);
                } catch (NumberFormatException e) {

View on GitHub (pinned to 567142e072)