TheAlgorithms/Java · error · IllegalArgumentException

Not a valid IPv6-mapped IPv4 address.

Error message

Not a valid IPv6-mapped IPv4 address.

What it means

Thrown by IPv6Converter.ipv6ToIpv4 as an IllegalArgumentException when the resolved address does not have the IPv6-mapped IPv4 prefix (80 zero bits followed by 0xFFFF). Only addresses matching the pattern ::ffff:x.x.x.x are accepted; all other IPv6 addresses are rejected. The internal isValidIpv6MappedIpv4 checks that the 16-byte array has bytes 0–9 set to zero and bytes 10–11 set to 0xFF.

Source

Thrown at src/main/java/com/thealgorithms/conversions/IPv6Converter.java:72

    /**
     * Extracts the IPv4 address from an IPv6-mapped IPv6 address.
     * Example: IPv6 "::ffff:192.0.2.128" -> IPv4 "192.0.2.128"
     *
     * @param ipv6Address The IPv6 address in string format.
     * @return The extracted IPv4 address.
     * @throws UnknownHostException If the IPv6 address is invalid or not a mapped IPv4 address.
     */
    public static String ipv6ToIpv4(String ipv6Address) throws UnknownHostException {
        InetAddress ipv6 = InetAddress.getByName(ipv6Address);
        byte[] ipv6Bytes = ipv6.getAddress();

        // Check if the address is an IPv6-mapped IPv4 address
        if (isValidIpv6MappedIpv4(ipv6Bytes)) {
            byte[] ipv4Bytes = Arrays.copyOfRange(ipv6Bytes, 12, 16);
            InetAddress ipv4 = InetAddress.getByAddress(ipv4Bytes);
            return ipv4.getHostAddress();
        } else {
            throw new IllegalArgumentException("Not a valid IPv6-mapped IPv4 address.");
        }
    }

    /**
     * Helper function to check if the given byte array represents
     * an IPv6-mapped IPv4 address (prefix 0:0:0:0:0:ffff).
     *
     * @param ipv6Bytes Byte array representation of the IPv6 address.
     * @return True if the address is IPv6-mapped IPv4, otherwise false.
     */
    private static boolean isValidIpv6MappedIpv4(byte[] ipv6Bytes) {
        // IPv6-mapped IPv4 addresses are 16 bytes long, with the first 10 bytes set to 0,
        // followed by 0xff, 0xff, and the last 4 bytes representing the IPv4 address.
        if (ipv6Bytes.length != 16) {
            return false;
        }

        for (int i = 0; i < 10; i++) {

View on GitHub (pinned to fdfb9a395b)

Solutions

1. Before calling ipv6ToIpv4, check that the address string starts with '::ffff:' or use InetAddress to inspect whether it is IPv4-mapped.
2. If you need to handle both native IPv6 and IPv4-mapped addresses, branch on the address type first using InetAddress.getByName(addr).getAddress().length.
3. Catch IllegalArgumentException and fall back to returning the original address if it is not IPv4-mapped.

Example fix

// before
String ipv4 = IPv6Converter.ipv6ToIpv4(addr); // addr may be native IPv6

// after
String ipv4;
try {
    ipv4 = IPv6Converter.ipv6ToIpv4(addr);
} catch (IllegalArgumentException e) {
    // Not an IPv4-mapped address; handle as native IPv6 or IPv4
    ipv4 = addr; // or log and skip
}

InetAddress addr = InetAddress.getByName(ipv6Address);
byte[] bytes = addr.getAddress();
boolean isMapped = bytes.length == 16
    && bytes[0] == 0 && bytes[1] == 0 && bytes[2] == 0 && bytes[3] == 0
    && bytes[4] == 0 && bytes[5] == 0 && bytes[6] == 0 && bytes[7] == 0
    && bytes[8] == 0 && bytes[9] == 0 && bytes[10] == (byte) 0xff && bytes[11] == (byte) 0xff;
if (!isMapped) {
    throw new IllegalArgumentException("Not an IPv4-mapped IPv6 address");
}

try {
    String ipv4 = IPv6Converter.ipv6ToIpv4(ipv6Address);
} catch (IllegalArgumentException e) {
    // not an IPv4-mapped address; treat as native IPv6 or return original
    String ipv4 = ipv6Address;
}

When it happens

Trigger: Calling ipv6ToIpv4 with a native IPv6 address like '2001:db8::1'. Passing an address that is actually an IPv4 literal (4 bytes), which gets resolved to a 4-byte array that fails the 16-byte length check. Passing '::1' (loopback) or any address without the ::ffff: prefix.

Common situations: Receiving an address from a socket or HTTP header that may be IPv4, IPv4-mapped IPv6, or native IPv6. Accepting user-entered addresses that could be either format. Logs from a dual-stack server where some connections arrive as native IPv6.

Related errors

• IPv4 address is empty.
• Theta (angle) must be a finite number.
• Base must be between 2 and 36
• Decimal number cannot be negative.
• Invalid hexadecimal character: {}

AI-assisted analysis of TheAlgorithms/Java@fdfb9a395b (2026-08-13). Data as JSON: /api/errors/aa95682b5d46bb6d. Report an issue: GitHub.