Classify LLM provider connection errors with actionable hints

When the JVM cannot validate a custom provider's TLS certificate
(common with corporate / private CAs), users were shown a raw PKIX
stack trace with no hint about how to fix it — even though ECA
already supports `network.caCertFile` and `SSL_CERT_FILE`.

Add `llm-util/classify-connection-exception`, which walks the
exception cause chain and produces user-friendly messages for
SSL/TLS, DNS, connection-refused and timeout failures, pointing
users to the relevant config when one applies. The five catch
sites in the OpenAI, OpenAI-chat, Anthropic and Ollama providers
now share this helper.

Closes #457

🤖 Generated with [eca](https://eca.dev)

Co-Authored-By: eca-agent <git@eca.dev>

Author: ericdallo

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 - Improve CPU usage while streaming tool-call arguments by reusing the prompt's tool list.
+- Improve connection error messages from LLM providers. #457
 
 ## 0.133.4
 

src/eca/llm_providers/anthropic.clj

@@ -161,7 +161,7 @@
 
                       :else
                       (on-error {:exception e
-                                 :message (format "Connection error: %s" (or (ex-message e) (.getName (class e))))}))))
+                                 :message (llm-util/connection-error-message e)}))))
                 (finally
                   (stop-fn))))
             (do
@@ -170,7 +170,7 @@
                       {:output-text (:text (last (:content body)))})))))
       (catch Exception e
         (on-error {:exception e
-                   :message (format "Connection error: %s" (or (ex-message e) (.getName (class e))))})))
+                   :message (llm-util/connection-error-message e)})))
     @response*))
 
 (defn ^:private normalize-messages [past-messages supports-image?]

src/eca/llm_providers/ollama.clj

@@ -90,7 +90,7 @@
                       {:output-text (:content (:message body))})))))
       (catch Exception e
         (on-error {:exception e
-                   :message (format "Connection error: %s" (or (ex-message e) (.getName (class e))))})))
+                   :message (llm-util/connection-error-message e)})))
     @response*))
 
 (defn ^:private ->tools [tools]

src/eca/llm_providers/openai.clj

@@ -96,10 +96,10 @@
               (llm-util/log-response logger-tag rid "response" body)
               (response-body->result body)))))
       (catch Exception e
-        (let [msg (or (ex-message e) (.getName (class e)))
-              prefix (if (ex-data e) "Internal error" "Connection error")]
-          (on-error {:exception e
-                     :message (format "%s: %s" prefix msg)}))))))
+        (on-error {:exception e
+                   :message (if (ex-data e)
+                              (format "Internal error: %s" (or (ex-message e) (.getName (class e))))
+                              (llm-util/connection-error-message e))})))))
 
 (defn ^:private normalize-messages [messages supports-image?]
   ;; Each history entry maps to one or more provider messages. Switched from

src/eca/llm_providers/openai_chat.clj

@@ -154,7 +154,7 @@
               (response-body->result body on-tools-called-wrapper)))))
       (catch Exception e
         (on-error {:exception e
-                   :message (format "Connection error: %s" (or (ex-message e) (.getName (class e))))})))))
+                   :message (llm-util/connection-error-message e)})))))
 
 (defn ^:private transform-message
   "Transform a single ECA message to OpenAI format. Returns nil for unsupported roles.

src/eca/llm_util.clj

@@ -8,7 +8,10 @@
    [eca.secrets :as secrets]
    [eca.shared :as shared])
   (:import
-   [java.io BufferedReader Closeable]))
+   [java.io BufferedReader Closeable]
+   [java.net ConnectException SocketTimeoutException UnknownHostException]
+   [java.net.http HttpConnectTimeoutException]
+   [javax.net.ssl SSLException]))
 
 (set! *warn-on-reflection* true)
 
@@ -156,3 +159,76 @@
               (some-> (get-in config [:providers (name provider) :urlEnv]) config/get-env)) ;; legacy
           shared/normalize-api-url
           not-empty))
+
+(defn ^:private cause-chain
+  "Returns a seq of `e` followed by every nested cause."
+  [^Throwable e]
+  (->> (iterate (fn [^Throwable t] (.getCause t)) e)
+       (take-while some?)))
+
+(defn ^:private root-message [^Throwable e]
+  (or (ex-message e) (.getName (class e))))
+
+(defn classify-connection-exception
+  "Walks the cause chain of `e` and classifies common HTTP/TLS failures
+   into a user-friendly map: {:kind <keyword> :message <string>}.
+
+   Recognized kinds:
+   - :tls-untrusted   - PKIX path building failed (private/corporate CA not trusted)
+   - :tls-other       - other TLS/SSL handshake errors
+   - :dns             - UnknownHostException
+   - :connect-refused - ConnectException (connection refused, etc.)
+   - :timeout         - connection/socket timeouts
+   - :unknown         - fallback; keeps the historical 'Connection error: ...' format"
+  [^Throwable e]
+  (let [msg (root-message e)
+        causes (cause-chain e)
+        pkix? (some (fn [^Throwable c]
+                      (some-> (ex-message c)
+                              (string/includes? "PKIX path building failed")))
+                    causes)
+        ssl?  (some #(instance? SSLException %) causes)
+        dns?  (some #(instance? UnknownHostException %) causes)
+        connect-refused? (some #(instance? ConnectException %) causes)
+        timeout? (some #(or (instance? HttpConnectTimeoutException %)
+                            (instance? SocketTimeoutException %))
+                       causes)]
+    (cond
+      pkix?
+      {:kind :tls-untrusted
+       :message (str "TLS certificate not trusted: PKIX path building failed. "
+                     "The server's certificate is signed by a CA not in the JVM truststore "
+                     "(common with private/corporate CAs). "
+                     "Fix: set `network.caCertFile` in your ECA config or the `SSL_CERT_FILE` "
+                     "env var to a PEM bundle containing the missing CA. "
+                     "See docs/config/network.md for details. Original error: " msg)}
+
+      ssl?
+      {:kind :tls-other
+       :message (str "TLS error: " msg
+                     ". See docs/config/network.md for trust and mTLS configuration.")}
+
+      dns?
+      {:kind :dns
+       :message (str "DNS resolution failed: " msg
+                     ". Check the provider URL and your network/proxy settings.")}
+
+      connect-refused?
+      {:kind :connect-refused
+       :message (str "Could not connect: " msg
+                     ". Check the provider URL and whether the server is reachable. "
+                     "Corporate networks may require HTTP_PROXY / HTTPS_PROXY env vars.")}
+
+      timeout?
+      {:kind :timeout
+       :message (str "Connection timed out: " msg ".")}
+
+      :else
+      {:kind :unknown
+       :message (format "Connection error: %s" msg)})))
+
+(defn connection-error-message
+  "Returns a user-friendly message describing a connection-level exception.
+   Always non-nil. See `classify-connection-exception` for recognized error kinds."
+  [^Throwable e]
+  (:message (classify-connection-exception e)))

test/eca/llm_util_test.clj

@@ -7,7 +7,9 @@
    [eca.secrets :as secrets]
    [matcher-combinators.test :refer [match?]])
   (:import
-   [java.io ByteArrayInputStream]))
+   [java.io ByteArrayInputStream]
+   [java.net ConnectException SocketTimeoutException UnknownHostException]
+   [javax.net.ssl SSLException SSLHandshakeException]))
 
 (deftest event-data-seq-test
   (testing "when there is a event line and another data line"
@@ -185,4 +187,69 @@
 
   (testing "returns nil for blank url"
     (with-redefs [config/get-env (constantly nil)]
-      (is (nil? (llm-util/provider-api-url "openai" {:providers {"openai" {:url "   "}}})))))) 
+      (is (nil? (llm-util/provider-api-url "openai" {:providers {"openai" {:url "   "}}}))))))
+
+(deftest classify-connection-exception-test
+  (testing "PKIX path building failed -> :tls-untrusted with actionable hint"
+    (let [e (SSLHandshakeException. "PKIX path building failed: unable to find valid certification path to requested target")
+          {:keys [kind message]} (llm-util/classify-connection-exception e)]
+      (is (= :tls-untrusted kind))
+      (is (re-find #"TLS certificate not trusted" message))
+      (is (re-find #"network\.caCertFile" message))
+      (is (re-find #"SSL_CERT_FILE" message))
+      (is (re-find #"docs/config/network\.md" message))))
+
+  (testing "PKIX detected even when wrapped in a non-SSL outer exception"
+    (let [root (Exception. "PKIX path building failed: unable to find valid certification path to requested target")
+          wrapped (RuntimeException. "wrapper" root)
+          {:keys [kind message]} (llm-util/classify-connection-exception wrapped)]
+      (is (= :tls-untrusted kind))
+      (is (re-find #"network\.caCertFile" message))))
+
+  (testing "Generic SSLException (no PKIX) -> :tls-other"
+    (let [e (SSLException. "handshake_failure")
+          {:keys [kind message]} (llm-util/classify-connection-exception e)]
+      (is (= :tls-other kind))
+      (is (re-find #"TLS error" message))
+      (is (re-find #"docs/config/network\.md" message))))
+
+  (testing "UnknownHostException -> :dns"
+    (let [e (UnknownHostException. "no-such-host.example")
+          {:keys [kind message]} (llm-util/classify-connection-exception e)]
+      (is (= :dns kind))
+      (is (re-find #"DNS resolution failed" message))))
+
+  (testing "ConnectException (e.g. Connection refused) -> :connect-refused"
+    (let [e (ConnectException. "Connection refused")
+          {:keys [kind message]} (llm-util/classify-connection-exception e)]
+      (is (= :connect-refused kind))
+      (is (re-find #"Could not connect" message))
+      (is (re-find #"HTTP_PROXY" message))))
+
+  (testing "SocketTimeoutException -> :timeout"
+    (let [e (SocketTimeoutException. "Read timed out")
+          {:keys [kind message]} (llm-util/classify-connection-exception e)]
+      (is (= :timeout kind))
+      (is (re-find #"Connection timed out" message))))
+
+  (testing "Unknown exception falls back to legacy 'Connection error:' format"
+    (let [e (Exception. "boom")
+          {:keys [kind message]} (llm-util/classify-connection-exception e)]
+      (is (= :unknown kind))
+      (is (= "Connection error: boom" message))))
+
+  (testing "Exception with nil message uses class name as fallback"
+    (let [e (Exception.)
+          {:keys [kind message]} (llm-util/classify-connection-exception e)]
+      (is (= :unknown kind))
+      (is (re-find #"Connection error: java\.lang\.Exception" message)))))
+
+(deftest connection-error-message-test
+  (testing "returns the :message from classify-connection-exception"
+    (is (re-find #"TLS certificate not trusted"
+                 (llm-util/connection-error-message
+                  (SSLHandshakeException. "PKIX path building failed: ...")))))
+  (testing "is non-nil for any exception"
+    (is (string? (llm-util/connection-error-message (Exception. "x"))))
+    (is (string? (llm-util/connection-error-message (Exception.))))))
+