Why do developers get "authentication handshake failed: missing selected ALPN property" error with okteto deploy or build?

Help
1

When I run okteto deploy or okteto build, the command fails with this error:

authentication handshake failed: missing selected ALPN property
2

This error occurs due to differences in network infrastructure or client configurations that affect ALPN (Application-Layer Protocol Negotiation) support. Here’s what’s happening:

Root Cause: Okteto requires the load balancer to support ALPN to enable HTTP/2 connections. When ALPN negotiation fails, you get the “missing selected ALPN property” error during the authentication handshake.

Why it affects some developers but not others:

  • Different network configurations (corporate firewalls, proxies, VPNs)

  • Different versions of the Okteto CLI networking libraries

  • Network infrastructure that doesn’t properly support ALPN

Proper Solution: The real fix is to ensure that your load balancer and any network hops in between (e.g., VPN, corporate proxies, firewalls) properly support ALPN and HTTP/2. This requires:

  • Configuring load balancers to support ALPN protocol negotiation

  • Ensuring VPN clients/servers support HTTP/2 and ALPN

  • Updating network infrastructure that may be blocking or interfering with ALPN negotiation

  • Ensure that the Okteto load balancers support HTTP/2 and ALPN

Temporary Workaround

If you cannot immediately fix the network infrastructure, set the environment variable GRPC_ENFORCE_ALPN_ENABLED=false to disable ALPN enforcement:

For individual use

GRPC_ENFORCE_ALPN_ENABLED=false okteto deploy --remote --var “GH_TOKEN=$(gh auth token)” --log-level debug

For Windows:

$env:GRPC_ENFORCE_ALPN_ENABLED=“false”; okteto deploy --remote --var “GH_TOKEN=$(gh auth token)” --log-level debug

Team-wide workaround: Administrators can set GRPC_ENFORCE_ALPN_ENABLED=false in the Admin Variables section of the Okteto Admin Dashboard to apply this setting for all team members automatically.

Note: This workaround allows gRPC connections to fall back to HTTP/1.1 when ALPN negotiation fails, but fixing the underlying network infrastructure is the recommended long-term solution.