OpenVPN error: unrecognized option tls-remote or keysize

It usually starts with a profile that has connected for years, opened on a newer client, failing before the tunnel even starts. The terminal prints something like Options error: Unrecognized option ... in client.ovpn:130: tls-remote, with a version in parentheses at the end. Read it as a parser complaint: the file contains a directive that this client no longer knows.

That single message explains why regenerating keys, retyping the password, or checking the server does nothing. The failure happens while the client is reading its own configuration, before it opens a socket. The useful work is to identify the rejected directive and replace it with the current equivalent.

Read the failing line before editing anything

Run the client yourself instead of launching it from a tray icon, so the message is visible and the profile path is unambiguous. Open the file at the reported line and look at the token the client named. The line number is the profile line, not a version, which trips people up because the same number appears in the parentheses as a release identifier.

Old profile generators did not emit one bad directive; they emitted several. Fix the first error, rerun the client, and expect the next one to appear. That sequence is normal and not a sign that the edits made things worse.

What happened to keysize and tls-remote

keysize requested a cipher key length in the era when the profile chose the cipher explicitly. OpenVPN 2.4 deprecated it, and later clients removed it from the option table, so the parser now rejects the line instead of ignoring it. Modern negotiation derives the key length from the selected cipher, which is why there is nothing left for the directive to control.

tls-remote was removed in 2.4. It compared the server certificate against an expected name, and its replacement is verify-x509-name, which is stricter about how the name is matched. The old directive is gone, so a profile that carries it will never parse on a current client.

Fix one directive per attempt. If the profile also specifies a cipher that the client does not offer, that produces a different error later, and mixing both changes in one edit makes it impossible to tell which one broke the handshake. Reconnect after each edit and keep the error text. That habit also leaves a working fallback if an edit makes things worse.

Rewrite the server identity check

The replacement takes the expected name and a comparison mode. verify-x509-name vpn.example.edu name requires the certificate subject to equal that value exactly. Other modes match a prefix or a full subject string, and choosing the wrong mode turns a working profile into a clean verification failure.

If the old tls-remote argument was the server's full common name, an exact name comparison is usually right. If it was a partial value, use the prefix mode rather than shortening the expected name, because a shorter exact match will not verify. When the original value is not written down, ask whoever operates the server for the subject they publish.

Do not silence the check to make the error disappear. Removing server identity verification converts a fixable profile problem into an unverified tunnel, which is exactly the risk the directive existed to prevent.

Corrected profile, local edit, or older client

When someone else owns the server, the cleanest path is a current profile from them. Your copy came from an older generator, and their export already uses the current directives. One download removes the entire category of errors and keeps future edits in one place.

When you own both ends, edit a copy and keep the original. Change one directive, save, connect, and record the client version you tested. Keep a short note next to each edit, because a profile edited over several sessions is hard to audit from memory. Command-line runs against the edited file make that loop fast because the error goes straight to the terminal.

Pinning or rolling back to a pre-2.4 client also makes the message vanish, and with an appliance that will never be updated that may be the only workable stopgap. Treat it as temporary: an old client on a current desktop usually means an old library and an unsupported configuration, which is a problem deferred rather than solved.

After the tunnel comes up, read the whole profile once more. Profiles that carried one removed directive often carry another, and the second only surfaces after the first is gone.