From b84da492aad5e02e07dc8383362689c4041f83be Mon Sep 17 00:00:00 2001
From: Jiya Gupta <141018273+Jiya873@users.noreply.github.com>
Date: Tue, 16 Dec 2025 18:51:37 +0530
Subject: [PATCH] DOC: clarify ZarrTrace incompatibility with external samplers

---
 pymc/sampling/mcmc.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/pymc/sampling/mcmc.py b/pymc/sampling/mcmc.py
index de341c68cd..174e3b33b9 100644
--- a/pymc/sampling/mcmc.py
+++ b/pymc/sampling/mcmc.py
@@ -586,6 +586,12 @@ def sample(
         of their execution will write the partial results onto the storage. If the
         storage persist on disk, these results should be available even after a server
         crash. See :class:`~pymc.backends.zarr.ZarrTrace` for more information.
+        .. note::
+
+            The ``ZarrTrace`` backend is currently only supported when using
+            PyMC’s built-in samplers. It is not compatible with external samplers
+            such as NumPyro (``nuts_sampler="numpyro"``), which bypass PyMC’s
+            internal sampling loop.
     discard_tuned_samples : bool
         Whether to discard posterior samples of the tune interval.
     compute_convergence_checks : bool, default=True