Warn instead of error on combine='nested' with concat_dim supplied

doc/user-guide/io.rst

@@ -246,7 +246,7 @@ See its docstring for more details.
     across the datasets (ignoring floating point differences). The following command
     with suitable modifications (such as ``parallel=True``) works well with such datasets::
 
-         xr.open_mfdataset('my/files/*.nc', concat_dim="time",
+         xr.open_mfdataset('my/files/*.nc', concat_dim="time", combine="nested",
      	              	   data_vars='minimal', coords='minimal', compat='override')
 
     This command concatenates variables along the ``"time"`` dimension, but only those that

doc/whats-new.rst

@@ -100,13 +100,6 @@ New Features
   expand, ``False`` to always collapse, or ``default`` to expand unless over a
   pre-defined limit (:pull:`5126`).
   By `Tom White <https://github.com/tomwhite>`_.
-- Prevent passing `concat_dim` to :py:func:`xarray.open_mfdataset` when
-  `combine='by_coords'` is specified, which should never have been possible (as
-  :py:func:`xarray.combine_by_coords` has no `concat_dim` argument to pass to).
-  Also removes unneeded internal reordering of datasets in
-  :py:func:`xarray.open_mfdataset` when `combine='by_coords'` is specified.
-  Fixes (:issue:`5230`).
-  By `Tom Nicholas <https://github.com/TomNicholas>`_.
 - Implement ``__setitem__`` for :py:class:`core.indexing.DaskIndexingAdapter` if
   dask version supports item assignment. (:issue:`5171`, :pull:`5174`)
   By `Tammas Loughran <https://github.com/tammasloughran>`_.
@@ -131,6 +124,15 @@ Breaking changes
 Deprecations
 ~~~~~~~~~~~~
 
+- Warn when passing `concat_dim` to :py:func:`xarray.open_mfdataset` when
+  `combine='by_coords'` is specified, which should never have been possible (as
+  :py:func:`xarray.combine_by_coords` has no `concat_dim` argument to pass to).
+  Also removes unneeded internal reordering of datasets in
+  :py:func:`xarray.open_mfdataset` when `combine='by_coords'` is specified.
+  Fixes (:issue:`5230`), via (:pull:`5231`, :pull:`5255`).
+  By `Tom Nicholas <https://github.com/TomNicholas>`_.
+
+
 Bug fixes
 ~~~~~~~~~
 - Properly support :py:meth:`DataArray.ffill`, :py:meth:`DataArray.bfill`, :py:meth:`Dataset.ffill`, :py:meth:`Dataset.bfill` along chunked dimensions.

xarray/backends/api.py

@@ -1,4 +1,5 @@
 import os
+import warnings
 from glob import glob
 from io import BytesIO
 from numbers import Number
@@ -890,10 +891,14 @@ def open_mfdataset(
             list(combined_ids_paths.values()),
         )
 
+    # TODO raise an error instead of a warning after v0.19
     elif combine == "by_coords" and concat_dim is not None:
-        raise ValueError(
-            "`concat_dim` can only be used with combine='nested',"
-            " not with combine='by_coords'"
+        warnings.warn(
+            "When combine='by_coords', passing a value for `concat_dim` has no "
+            "effect. This combination will raise an error in future. To manually "
+            "combine along a specific dimension you should instead specify "
+            "combine='nested' along with a value for `concat_dim`.",
+            DeprecationWarning,
         )
 
     open_kwargs = dict(engine=engine, chunks=chunks or {}, **kwargs)

xarray/tests/test_backends.py

@@ -3409,14 +3409,17 @@ def test_open_mfdataset_auto_combine(self):
                 with open_mfdataset([tmp2, tmp1], combine="by_coords") as actual:
                     assert_identical(original, actual)
 
+    # TODO check for an error instead of a warning once deprecated
     def test_open_mfdataset_raise_on_bad_combine_args(self):
         # Regression test for unhelpful error shown in #5230
         original = Dataset({"foo": ("x", np.random.randn(10)), "x": np.arange(10)})
         with create_tmp_file() as tmp1:
             with create_tmp_file() as tmp2:
                 original.isel(x=slice(5)).to_netcdf(tmp1)
                 original.isel(x=slice(5, 10)).to_netcdf(tmp2)
-                with pytest.raises(ValueError, match="`concat_dim` can only"):
+                with pytest.warns(
+                    DeprecationWarning, match="`concat_dim` has no effect"
+                ):
                     open_mfdataset([tmp1, tmp2], concat_dim="x")
 
     @pytest.mark.xfail(reason="mfdataset loses encoding currently.")