How to Write an IPv6 Endpoint in a VPN Configuration

An IPv6 address is full of colons, and an endpoint field that also carries a port needs a way to mark where the address ends. Get that wrong and the client either refuses to parse the profile or silently connects to the wrong thing. The correct form is not universal: it depends on whether the field holds an address plus port, a bare address, or a hostname. Work through the runbook in order, because a syntax fix and a reachability fix look nothing alike once you are reading the client's output.

Check the field type before you type an address

For a WireGuard Endpoint field, an IPv6 literal with a port uses brackets around the address, as in [2001:db8::10]:51820. The documentation prefix in that example is not a public server, and the brackets are part of the syntax rather than part of the address.

Other formats have their own rules. A URI can carry an IPv6 literal in brackets, but a VPN configuration is not necessarily a URI. A client with separate address and port boxes may expect the literal alone in one box and the number in another, and adding brackets there is just as wrong as omitting them in a combined field.

Bracket the literal when a port shares the field

The rule to remember is simple: brackets appear when a port follows in the same string. They do not appear when the address stands alone in a field that has no port.

Copying one protocol's complete endpoint string into every client is the usual source of this error. OpenVPN, IPsec profiles, and application interfaces each document their own syntax, and a string that is correct for one may be rejected or misinterpreted by another. Read the client's own documentation for the field you are editing, and keep the documentation prefix or example address in a comment so nobody ships it as a real host. When the manual gives two forms, use the one that matches the field type in front of you.

Separate address and port fields

When the client gives you two boxes, put the address in one and the port in the other. A combined form pasted into the address box produces a parse error or, worse, an address that resolves to something unintended.

Check for trailing spaces and invisible characters when a value looks correct. A copied address often carries a non-breaking space or a zero-width character that the client cannot parse and the screen does not show. Retype the value instead of pasting it when the error makes no sense.

Handle zone identifiers carefully

A link-local literal can require a zone identifier tied to an interface, written with a percent sign and the interface name. That form is valid on the host that owns the interface, and it is not a substitute for a generally reachable remote endpoint.

Scope and routing still matter after parsing succeeds. A zone-qualified address that the client accepts may have no path from the machine, and a remote endpoint reached over the internet should not depend on a local zone at all. Decide which interface the packet should leave through before you write the zone, not after the handshake fails.

Verify parsing, then verify reachability

Separate the two failures explicitly. A malformed address produces a parse error or an immediate rejection, while a well-formed endpoint that rejects authentication or never answers is a different problem with a different fix.

After a supported correction, confirm that the tunnel negotiates and that the intended application works. A handshake alone does not prove the path, and a ping to the endpoint does not prove the tunnel. Where the operator supplies a hostname, keep the supported name and its identity checks rather than replacing it with a numeric address found elsewhere.

Record the exact field, the value you used, and the client's response in the change note. The next person to edit the profile will otherwise repeat the bracket experiment, and the answer is already in your ticket.