{"record":{"id":"285c741006b4f071","repo":"grpc/grpc-go","slug":"credentials-cannot-check-peer-missing-selected-a","errorCode":null,"errorMessage":"credentials: cannot check peer: missing selected ALPN property. %s","messagePattern":"credentials: cannot check peer: missing selected ALPN property\\. (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"credentials/tls.go","lineNumber":151,"sourceCode":"\t\t\treturn nil, nil, err\n\t\t}\n\tcase <-ctx.Done():\n\t\tconn.Close()\n\t\treturn nil, nil, ctx.Err()\n\t}\n\n\t// The negotiated protocol can be either of the following:\n\t// 1. h2: When the server supports ALPN. Only HTTP/2 can be negotiated since\n\t//    it is the only protocol advertised by the client during the handshake.\n\t//    The tls library ensures that the server chooses a protocol advertised\n\t//    by the client.\n\t// 2. \"\" (empty string): If the server doesn't support ALPN. ALPN is a requirement\n\t//    for using HTTP/2 over TLS. We can terminate the connection immediately.\n\tnp := conn.ConnectionState().NegotiatedProtocol\n\tif np == \"\" {\n\t\tif envconfig.EnforceALPNEnabled {\n\t\t\tconn.Close()\n\t\t\treturn nil, nil, fmt.Errorf(\"credentials: cannot check peer: missing selected ALPN property. %s\", alpnFailureHelpMessage)\n\t\t}\n\t\tlogger.Warningf(\"Allowing TLS connection to server %q with ALPN disabled. TLS connections to servers with ALPN disabled will be disallowed in future grpc-go releases\", cfg.ServerName)\n\t}\n\ttlsInfo := TLSInfo{\n\t\tState: conn.ConnectionState(),\n\t\tCommonAuthInfo: CommonAuthInfo{\n\t\t\tSecurityLevel: PrivacyAndIntegrity,\n\t\t},\n\t}\n\tid := credinternal.SPIFFEIDFromState(conn.ConnectionState())\n\tif id != nil {\n\t\ttlsInfo.SPIFFEID = id\n\t}\n\treturn credinternal.WrapSyscallConn(rawConn, conn), tlsInfo, nil\n}\n\nfunc (c *tlsCreds) ServerHandshake(rawConn net.Conn) (net.Conn, AuthInfo, error) {\n\tconn := tls.Server(rawConn, c.config)","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/grpc/grpc-go/blob/03255a9237b6eb32710f6bc4f2de9a675b99fe36/credentials/tls.go#L133-L169","documentation":"Returned by tlsCreds.ClientHandshake in credentials/tls.go:151 when, after a successful TLS handshake, no ALPN protocol was negotiated (NegotiatedProtocol == \"\") and envconfig.EnforceALPNEnabled is true (the default). HTTP/2 over TLS requires ALPN, so grpc-go refuses connections to ALPN-less servers. The trailing %s points at issue #434 and the 1.67 enforcement change.","triggerScenarios":"Dialing a TLS server (or a proxy/terminator in front of it) that does not support ALPN, while GRPC_ENFORCE_ALPN_ENABLED is true (default). Common after upgrading grpc-go to >=1.67.","commonSituations":"Post-1.67 upgrade where TLS connections to an older server/proxy stopped working; an HAProxy/nginx/cloud LB that did not enable h2 ALPN; servers configured with TLS but no NextProtos.","solutions":["Enable h2 ALPN on the server / TLS terminator (nginx: http2 + ssl_alpn, or grpc ALPN; Go server: rely on grpc's default NextProtos).","As a temporary rollback, set GRPC_ENFORCE_ALPN_ENABLED=false in the client environment (will be removed in a future release).","Bypass the ALPN-stripping proxy for the gRPC port."],"exampleFix":"// before: client env (default)\n// GRPC_ENFORCE_ALPN_ENABLED unset -> enforcement on, connection fails\n\n// after (fix the server): nginx\n//   listen 443 ssl http2;\n//   ssl_alpn h2 http/1.1;\n\n// after (temporary client-side rollback)\n//   export GRPC_ENFORCE_ALPN_ENABLED=false","handlingStrategy":"validation","validationCode":"// Ensure the server/terminator advertises h2 ALPN before enforcing.\n// Client-side mitigation: do nothing if server is ALPN-capable.\n// Temporary rollback only for migration:\n// os.Setenv(\"GRPC_ENFORCE_ALPN_ENABLED\", \"false\") // must be set before grpc imports init","typeGuard":null,"tryCatchPattern":"if strings.Contains(err.Error(), \"missing selected ALPN property\") {\n    // server lacks ALPN; enable h2 on the server/terminator or set\n    // GRPC_ENFORCE_ALPN_ENABLED=false as a temporary rollback\n}","preventionTips":["Enable h2 ALPN on all TLS terminators in front of gRPC servers.","Test the ALPN upgrade path in staging before enforcing in production.","Treat GRPC_ENFORCE_ALPN_ENABLED=false as migration-only; track upstream removal."],"tags":["tls","alpn","http2","compatibility","transport","go"],"analyzedSha":"03255a9237b6eb32710f6bc4f2de9a675b99fe36","analyzedAt":"2026-08-07T00:29:34.215Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}