From a8ce91ebf1830e88d184d88e8630bfb0ab61a6da Mon Sep 17 00:00:00 2001
From: Niklas Mohrin <dev@niklasmohrin.de>
Date: Sat, 21 Feb 2026 00:07:45 +0100
Subject: [PATCH] Add note about changing tls_backend setting

---
 src/config.rs | 10 +++++++++-
 src/main.rs   | 32 +++++++++++++++++++++++++++++---
 2 files changed, 38 insertions(+), 4 deletions(-)

diff --git a/src/config.rs b/src/config.rs
index e5e85e8..d786a8f 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
 }
@@ -460,7 +468,7 @@ 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(),
             ))
         }
     }
diff --git a/src/main.rs b/src/main.rs
index a0cd593..0c9bc4f 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