From 47a936e7363ca2afd6a8513862cceccf044d6bf8 Mon Sep 17 00:00:00 2001
From: Niklas Mohrin <dev@niklasmohrin.de>
Date: Sat, 21 Feb 2026 00:32:23 +0100
Subject: [PATCH] Suggest trying different TLS backend when update fails (#465)

Closes #453

- Add note about changing tls_backend setting
- impl Display for TlsBackend
- Remove trailing slash in default archive source to make URL in error
look nicer
---
 src/config.rs | 31 +++++++++++++++++++++++++++++--
 src/main.rs   | 32 +++++++++++++++++++++++++++++---
 2 files changed, 58 insertions(+), 5 deletions(-)

diff --git a/src/config.rs b/src/config.rs
index e5e85e8..2c39235 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -31,6 +31,14 @@ const SUPPORTED_TLS_BACKENDS: &[RawTlsBackend] = &[
     RawTlsBackend::RustlsWithNativeRoots,
 ];
 
+pub(crate) fn supported_tls_backends_string() -> String {
+    SUPPORTED_TLS_BACKENDS
+        .iter()
+        .map(std::string::ToString::to_string)
+        .collect::<Vec<String>>()
+        .join(", ")
+}
+
 fn default_underline() -> bool {
     false
 }
@@ -184,7 +192,7 @@ const fn default_auto_update_interval_hours() -> u64 {
 }
 
 fn default_archive_source() -> String {
-    "https://github.com/tldr-pages/tldr/releases/latest/download/".to_owned()
+    "https://github.com/tldr-pages/tldr/releases/latest/download".to_owned()
 }
 
 #[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
@@ -460,12 +468,31 @@ impl TryFrom<RawTlsBackend> for TlsBackend {
             _ => Err(anyhow!(
                 "Unsupported TLS backend: {}. This tealdeer build has support for the following options: {}",
                 raw,
-                SUPPORTED_TLS_BACKENDS.iter().map(std::string::ToString::to_string).collect::<Vec<String>>().join(", ")
+                supported_tls_backends_string(),
             ))
         }
     }
 }
 
+impl TlsBackend {
+    const fn as_raw(self) -> RawTlsBackend {
+        match self {
+            #[cfg(feature = "native-tls")]
+            Self::NativeTls => RawTlsBackend::NativeTls,
+            #[cfg(feature = "rustls-with-webpki-roots")]
+            Self::RustlsWithWebpkiRoots => RawTlsBackend::RustlsWithWebpkiRoots,
+            #[cfg(feature = "rustls-with-native-roots")]
+            Self::RustlsWithNativeRoots => RawTlsBackend::RustlsWithNativeRoots,
+        }
+    }
+}
+
+impl fmt::Display for TlsBackend {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        self.as_raw().fmt(f)
+    }
+}
+
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct Config<'a> {
     pub style: StyleConfig,
diff --git a/src/main.rs b/src/main.rs
index a0cd593..1d1b5fc 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -55,7 +55,9 @@ mod utils;
 use crate::{
     cache::{Cache, PageLookupResult, TLDR_PAGES_DIR},
     cli::Cli,
-    config::{get_config_dir, make_default_config, Config, PathWithSource},
+    config::{
+        get_config_dir, make_default_config, supported_tls_backends_string, Config, PathWithSource,
+    },
     output::print_page,
     types::ColorOptions,
     utils::{print_error, print_warning},
@@ -305,12 +307,36 @@ fn try_main(args: Cli, enable_styles: bool) -> Result<ExitCode> {
     let cache = if args.update || config.updates.auto_update && !args.no_auto_update {
         let (mut cache, was_created) = Cache::open_or_create(cache_config)?;
         if was_created || args.update || cache.age()? >= config.updates.auto_update_interval {
-            update_cache(
+            let result = update_cache(
                 &mut cache,
                 config.updates.archive_source,
                 config.updates.tls_backend,
                 args.quiet,
-            )?;
+            );
+
+            if let Err(e) = result {
+                print_error(enable_styles, &e);
+
+                eprintln!();
+                eprintln!("Note: Update errors are often caused by unexpected or missing TLS certificates.");
+                eprintln!(
+                    "You are currently using the following TLS backend: {}",
+                    config.updates.tls_backend,
+                );
+                eprintln!(
+                    "Try changing the updates.tls_backend setting in the config file, for example:"
+                );
+                eprintln!();
+                eprintln!("  [updates]");
+                eprintln!("  tls_backend = \"rustls-with-native-roots\"");
+                eprintln!();
+                eprintln!(
+                    "This build of tealdeer has support for the following options: {}",
+                    supported_tls_backends_string(),
+                );
+
+                return Ok(ExitCode::FAILURE);
+            }
         }
 
         cache