[UX] Improve "unknown certificate verification error" with actionable guidance for network/proxy failures #36590

Summary

The error message unknown certificate verification error is shown verbatim when network connectivity to the LLM provider fails (e.g., VPN disconnect, proxy interference, temporary outage). This raw error string is opaque to end users and provides no actionable troubleshooting guidance.

Problem

When the network becomes unavailable or a proxy/VPN intercepts TLS traffic, OpenCode surfaces the raw underlying error:

unknown certificate verification error

This is unhelpful because:

1. No context — it doesn't indicate which provider endpoint or operation failed
2. No root-cause hint — users can't tell whether this is a network outage, VPN issue, proxy/corporate firewall, or an actual certificate problem
3. No remediation guidance — no suggested next steps are provided
4. Misleading — "certificate verification error" suggests a certificate misconfiguration, when the actual cause is often simply network unavailability

Context

While using OpenCode on macOS (v1.17.18) with the zhipuai/glm-5.2 model provider, the network connection became temporarily unavailable. OpenCode displayed unknown certificate verification error with no additional context. The user had to manually diagnose that the root cause was a network/VPN issue, not a certificate problem.

This is not an isolated case — multiple existing issues report the same error under various conditions:

• Error: unknown certificate verification error #8601 — Error on Windows when switching AI providers
• macOS intermittent UNKNOWN_CERTIFICATE_VERIFICATION_ERROR for OpenAI/Codex endpoint under proxy conditions #21206 — macOS intermittent error under proxy conditions (regression in 1.3.17)
• Sessions fail on transient network errors instead of retrying #30611 — Sessions fail on transient network errors instead of retrying
• Desktop/Server: Auto-updater and models.dev fetch lack network resilience (excessive errors in restricted networks) #35090 — Auto-updater and models.dev fetch lack network resilience

Suggested Improvement

Map common TLS/network errors to user-friendly messages with remediation hints. For example:

⚠️ Network Connection Error

Unable to reach the AI provider (zhipuai/glm-5.2).

Common causes:
  • Network connectivity issues — check your internet connection
  • VPN disconnection — verify your VPN is active
  • Proxy/firewall interference — check proxy settings
  • Self-signed or expired certificates in your network path

Original error: unknown certificate verification error

Specific suggestions:

1. Identify the provider/endpoint in the error message (e.g., "Failed to connect to zhipuai API")
2. List common causes (network down, VPN, proxy, corporate firewall)
3. Suggest remediation steps (check network, verify VPN, review proxy config)
4. Preserve the original error for advanced debugging (collapsible or in logs)
5. Consider auto-retry with exponential backoff for transient network errors (as noted in Sessions fail on transient network errors instead of retrying #30611)

Environment

• OpenCode: 1.17.18
• OS: macOS (darwin)
• Provider: zhipuai/glm-5.2
• Trigger: network became temporarily unavailable during a coding session