From c5f76c878fc4ed7289ad2216c88133c7888cc4ce Mon Sep 17 00:00:00 2001
From: V1SHAL421 <vishalmkumar3@gmail.com>
Date: Sat, 16 May 2026 09:17:18 +0100
Subject: [PATCH 1/4] Fix KeyError when caplog handler is missing, raise
 RuntimeError instead

---
 src/_pytest/logging.py          | 5 ++++-
 testing/logging/test_fixture.py | 8 +++++++-
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/src/_pytest/logging.py b/src/_pytest/logging.py
index 2a22c9eb4aa..d138f8600dd 100644
--- a/src/_pytest/logging.py
+++ b/src/_pytest/logging.py
@@ -449,7 +449,10 @@ def _finalize(self) -> None:
     @property
     def handler(self) -> LogCaptureHandler:
         """Get the logging handler used by the fixture."""
-        return self._item.stash[caplog_handler_key]
+        handler = self._item.stash.get(caplog_handler_key, None)
+        if handler is None:
+            raise RuntimeError("caplog handler was not initialized for this test item")
+        return handler
 
     def get_records(
         self, when: Literal["setup", "call", "teardown"]
diff --git a/testing/logging/test_fixture.py b/testing/logging/test_fixture.py
index c98b7d84258..961dbb5f90e 100644
--- a/testing/logging/test_fixture.py
+++ b/testing/logging/test_fixture.py
@@ -5,7 +5,7 @@
 from collections.abc import Iterator
 import logging
 
-from _pytest.logging import caplog_records_key
+from _pytest.logging import caplog_handler_key, caplog_records_key
 from _pytest.pytester import Pytester
 import pytest
 
@@ -508,3 +508,9 @@ def test_that_fails(request, caplog):
         ["*Print message*", "*INFO log message*", "*WARNING log message*"]
     )
     assert result.ret == 1
+
+def test_caplog_missing_handler_raises_error(caplog):
+    del caplog._item.stash[caplog_handler_key]
+
+    with pytest.raises(RuntimeError, match="caplog handler was not initialized"):
+        _ = caplog.handler

From 493a7bada1e5f0c3e6079717ea6fa09a044964aa Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Sat, 16 May 2026 08:20:31 +0000
Subject: [PATCH 2/4] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 testing/logging/test_fixture.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/testing/logging/test_fixture.py b/testing/logging/test_fixture.py
index 961dbb5f90e..030423e4726 100644
--- a/testing/logging/test_fixture.py
+++ b/testing/logging/test_fixture.py
@@ -5,7 +5,8 @@
 from collections.abc import Iterator
 import logging
 
-from _pytest.logging import caplog_handler_key, caplog_records_key
+from _pytest.logging import caplog_handler_key
+from _pytest.logging import caplog_records_key
 from _pytest.pytester import Pytester
 import pytest
 
@@ -509,6 +510,7 @@ def test_that_fails(request, caplog):
     )
     assert result.ret == 1
 
+
 def test_caplog_missing_handler_raises_error(caplog):
     del caplog._item.stash[caplog_handler_key]
 

From 3982c21fe1f33035f5ab346c1435f1c48344174c Mon Sep 17 00:00:00 2001
From: V1SHAL421 <vishalmkumar3@gmail.com>
Date: Sat, 16 May 2026 09:20:38 +0100
Subject: [PATCH 3/4] Fix KeyError when caplog handler is missing, raise
 RuntimeError instead

---
 changelog/14488.bugfix.rst | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 changelog/14488.bugfix.rst

diff --git a/changelog/14488.bugfix.rst b/changelog/14488.bugfix.rst
new file mode 100644
index 00000000000..b54324ae9e3
--- /dev/null
+++ b/changelog/14488.bugfix.rst
@@ -0,0 +1 @@
+Raise a descriptive :class:`RuntimeError` instead of a :class:`KeyError` when accessing ``caplog.handler`` before it has been initialized.

From 83ac8cb00aba1a112a563d5294aabf8dcf42d3d9 Mon Sep 17 00:00:00 2001
From: V1SHAL421 <vishalmkumar3@gmail.com>
Date: Sat, 16 May 2026 09:31:34 +0100
Subject: [PATCH 4/4] fix: add type annotation for caplog

---
 testing/logging/test_fixture.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/testing/logging/test_fixture.py b/testing/logging/test_fixture.py
index 030423e4726..b8e29f053d2 100644
--- a/testing/logging/test_fixture.py
+++ b/testing/logging/test_fixture.py
@@ -511,7 +511,7 @@ def test_that_fails(request, caplog):
     assert result.ret == 1
 
 
-def test_caplog_missing_handler_raises_error(caplog):
+def test_caplog_missing_handler_raises_error(caplog: pytest.LogCaptureFixture) -> None:
     del caplog._item.stash[caplog_handler_key]
 
     with pytest.raises(RuntimeError, match="caplog handler was not initialized"):