IPv6 URL boundary lab · Updated November 13, 2026
Encode an IPv6 URL Without Breaking Brackets
Keep the square brackets around an IPv6 host structural; encode only the path or query value that is data. Encoding the whole host string turns the address into a different value and can make the URL parser reject it.
Three boundaries to compare
| Part | Keep or encode | Observed rule |
|---|---|---|
[2001:db8::1] | Keep brackets | They mark an IPv6 host inside a URL authority. |
:8443 | Keep colon | The port separator is structural after the closing bracket. |
q=a&tag=c+d | Encode values | Query ampersand separates parameters; plus may be data or a form-space convention. |
Node and PHP measured output
Run date: November 13, 2026. Node.js v24.19.0 and PHP 8.5.12 parse the same fixture with the IPv6 host intact.
Node.js v24.19.0 → hostname [2001:db8::1], port 8443, search ?q=a&tag=c+dPHP 8.5.12 parse_url → host [2001:db8::1], port 8443, query q=a&tag=c+d
Common failure
Do not run encodeURIComponent("[2001:db8::1]") when you mean a host. That creates data text for another context. Encode a query value such as c+d separately, then let the URL builder keep brackets and delimiters structural.
FAQ
Should an IPv6 address in a query be bracketed?
If it is a query value, it is data and may be encoded normally. Brackets are required for an IPv6 literal in the host position because the address itself contains colons.
Does encoding protect an IPv6 URL?
No. Encoding only prevents delimiter collisions; validation, authorization, and network policy remain separate.
For general component encoding, use the URL Encode tool. For parsed parts, use URL Format.