IPv6 URLs: Why Literal Addresses Need Square Brackets

An IPv6 URL needs square brackets around a literal address so a parser can separate the host from an optional port.

The rule matters when a copied address moves from a host field into a browser, request client, health check, or proxy URL. An IPv6 address contains colons. A URL also uses a colon before its port, so the brackets draw the boundary. If you first need to see which address family a connection exposes, use the ColdProxy public IP lookup. For the separate host-and-port concept, read how proxy host and port fields work.

Key Takeaways

• Bracket an IPv6 host only when it appears in a URL authority.
• Keep the port outside the closing bracket, as in https://[2001:db8::7]:443/status.
• Leave brackets out of a field that asks for a bare IP address.
• After parsing succeeds, check reachability, TLS, and proxy-client support as separate layers.

Why Does an IPv6 URL Need Square Brackets?

An IPv6 URL needs brackets because both the address and the optional port use colons. The bracket boundary lets the parser assign each colon to the right component.

Published in 2005, RFC 3986 says an Internet Protocol literal is "distinguished by enclosing the IP literal within square brackets". Its grammar places the bracketed literal in the host position of the URL authority.

Read this example from left to right:

• https:// is the scheme.
• [2001:db8::7] is the host, written as a bracketed IPv6 literal.
• :443 is the port.
• /status is the path.

The closing bracket assigns the following colon to the port. Splitting the raw string on every colon destroys that structure because the address itself can contain several colons.

What Do the Brackets Change in an IPv6 URL?

In a URL, the brackets are delimiters around the unchanged IPv6 address. The surrounding characters belong to URI syntax.

Published in 2006, RFC 4291 defines IPv6 addresses as 128-bit identifiers. Its preferred text form uses eight 16-bit pieces separated by colons, with shortening rules for zeros. Those address colons create the host-versus-port ambiguity inside a URL.

Field names tell you which grammar to use. In a host field, enter the bare literal and supply the port through its own field. In proxyUrl, endpoint, or baseUrl, enter the bracketed form because the value carries full URL syntax.

MDN's URL.hostname documentation describes the property as the domain-name or IP-address part of a URL and notes that IPv4 and IPv6 addresses are normalized. Parse once, then inspect hostname and port as separate properties.

What Did ColdProxy Observe With a Live IPv6 URL?

ColdProxy ran one redacted check on August 22, 2026 against the public IPv6 hostname used by the My IP service. The check retained DNS and parser outcomes; the live address and all location values were discarded.

Google DNS and Cloudflare DNS each returned one AAAA answer for api6.vipv6proxy.com. Their address sets matched. The parser check then placed that resolved address into two otherwise equivalent URL strings. The bracketed form produced the expected HTTPS scheme, host boundary, default port, and /api/checker/my-ip path. The unbracketed form failed with a TypeError.

The parser result applies to the URL implementation used in this check. The test environment recorded ENOENT for the hostname request and ENETUNREACH for the literal request. Those two errors support no conclusion about public endpoint availability or a shared failure cause.

In this check, adding the brackets resolved the ambiguous URL string.

Which IPv6 URL Form Should You Use: Hostname, Bracketed Literal, or Bare Address?

The input contract decides which form belongs in the field.

• Hostname in a URL: use this as the normal production choice when DNS, certificates, routing, and service configuration are built around a name.
• Bracketed IPv6 literal in a URL: use this for a direct-address diagnostic or a system that explicitly accepts literal URL hosts. Confirm certificate and client behavior before relying on it.
• Bare IPv6 address: use this in a documented address or host field, with the port supplied separately when required.

Use the bracket boundary check before entry: identify the field type, then format the literal once. This prevents a missing URL delimiter and stray brackets in address data.

Why Can a Correctly Bracketed IPv6 URL Still Fail?

After URL parsing, examine route availability, TLS identity, client behavior, and application policy.

• Route availability: the device and network still need a working IPv6 path to the destination.
• TLS identity: a certificate is usually issued for a hostname, so direct literal access can fail certificate validation. Server Name Indication through a proxy explains why the requested name can matter during TLS setup.
• Client contract: a library, proxy client, or configuration field may reject literal hosts or expect the port in a separate field.
• Application policy: the destination may route requests by hostname or apply different rules to direct-address traffic.
• Dual-stack behavior: when both families exist, the client may race available routes before choosing a family. See how Happy Eyeballs connection racing works.

Use this troubleshooting split: parsing answers "is this a valid URL structure?" Connection tests answer "can this client reach and use that destination?" Mixing the two questions leads to false diagnoses.

How Should You Validate an IPv6 URL?

1. Confirm whether the input expects a full URL, a host, or a bare address.
2. If it is a URL with an IPv6 literal, place the address inside [ and ], then keep :port outside.
3. Parse the complete URL with the same runtime or client that will use it. Inspect the parsed hostname, port, and path.
4. Test the hostname form and literal form separately. A difference helps isolate DNS, TLS identity, routing, or client policy from bracket syntax.
5. If a proxy is involved, verify the proxy client's accepted URL format before changing credentials or retrying the destination.

Record the first failing layer and its exact error.

What Should an IPv6 URL Error Report Include?

An actionable error report preserves the input shape and the first failing stage. Record these fields:

• Input contract: full URL, host, or address-only field.
• Sanitized value shape: keep the brackets and port position visible while replacing the literal address, path segments, query values, and fragment values with generic markers.
• Parser or client: name the software and record its exact error class.
• Parsed components: capture only a sanitized hostname form, the port, and a generic path marker when parsing succeeds.
• Next stage: label the DNS, route, TLS, or application result that followed.

Consider a monitoring job that moves a literal from a host setting into a baseUrl field. Its report can show the field type, a redacted bracket-and-port shape, the parser result, the parsed port, and the next recorded error. Another operator can then reproduce the same sequence without seeing the live address or request data.

Keep one timestamp and one client version with each attempt. Remove credentials, tokens, API keys, public or exit IPs, precise location values, customer identifiers, path secrets, query values, and fragments before sharing logs or support tickets. Clear field names and exact error classes make repeated tests comparable.

Share only a structural sample such as https://[REDACTED_IPV6]:443/[REDACTED_PATH] to show the bracket boundary and port placement. Strip the query string and fragment, or replace each with a generic marker when its presence matters to reproduction.

Does IPv6 Adoption Make Literal URLs the Better Default?

Hostnames remain the normal production default as IPv6 use grows because they preserve DNS and certificate identity.

In a study published in 2023, Cloudflare measured IPv6 adoption at roughly 36% of all traffic at the end of October 2023. Its estimate rose to just over 46% when excluding bots and fell close to 24% when excluding humans. These historical figures are scoped to Cloudflare traffic.

Parsers, tests, logs, and proxy configurations need to handle both address families without confusing an IPv6 colon with a port separator.

ColdProxy keeps its Residential IPv6 and Datacenter IPv6 options distinct because the network type, coverage model, and buying decision differ. The ColdProxy pricing page lists them separately.

Frequently Asked Questions

What is the correct IPv6 URL format?

Place the literal address between [ and ] in the URL's host position. Put any port after the closing bracket, for example https://[2001:db8::7]:443/status. Keep the scheme and path outside the brackets. If the application asks for a bare host instead of a URL, check its field rules first.

Are square brackets part of an IPv6 address?

No. Square brackets are URI delimiters around the address inside a URL. The colon-separated IPv6 value remains the address itself. When copying that value into an address-only field, use the inner value. The field's documentation determines whether it accepts URL delimiters.

Do square brackets guarantee that an IPv6 URL will connect?

No. After parsing, the request still depends on IPv6 reachability, compatible TLS identity, and client support for literal hosts. Test route availability and the application response after the parser accepts the URL. A connection can fail at any of those later stages.

Can a proxy URL use a bracketed IPv6 address?

Yes, when the proxy client accepts a complete URL with an IPv6 literal host. Keep the address bracketed and the port outside the closing bracket. Confirm the accepted proxy syntax in that client's documentation, then inspect the parsed host and port after entry when the interface exposes them.