Handle OSError download fallback for factor loader

factor_attribution.py

@@ -99,7 +99,7 @@ def load_external_us_factors(cache_dir: Path | str = "data/factors") -> pd.DataF
 
     try:
         raw_bytes = _download_kf_zip_bytes()
-    except (URLError, TimeoutError, ConnectionError) as exc:
+    except (URLError, TimeoutError, ConnectionError, OSError) as exc:
         if cache_path.exists():
             return _warn_and_load_cached_factors(cache_path, f"download failed: {exc}")
         raise

tests/test_factor_attribution.py

@@ -86,6 +86,32 @@ class ExternalFactorLoaderTests(unittest.TestCase):
         self.assertEqual(len(factors), 1)
         self.assertAlmostEqual(factors.iloc[0]["MKT_RF"], 0.01)
 
+    def test_load_external_us_factors_falls_back_to_cache_when_download_raises_oserror(self):
+        cached = pd.DataFrame(
+            {
+                "MKT_RF": [0.01],
+                "SMB": [0.0],
+                "HML": [0.0],
+                "RMW": [0.0],
+                "CMA": [0.0],
+                "RF": [0.0001],
+            },
+            index=pd.to_datetime(["2026-01-02"]),
+        )
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            cache_dir = Path(tmpdir)
+            cached.to_csv(cache_dir / "ff5_us_daily.csv")
+            with mock.patch(
+                "factor_attribution._download_kf_zip_bytes",
+                side_effect=OSError("transport reset"),
+            ):
+                with self.assertWarnsRegex(UserWarning, "cached data"):
+                    factors = load_external_us_factors(cache_dir=cache_dir)
+
+        self.assertEqual(len(factors), 1)
+        self.assertAlmostEqual(factors.iloc[0]["MKT_RF"], 0.01)
+
     def test_parse_kf_daily_csv_raises_external_factor_format_error_for_missing_header(self):
         zip_bytes = self._make_zip_bytes(
             "F-F_Research_Data_5_Factors_2x3_daily.csv",