Cannot call `set_eeg_reference` with a string for a channel name

[tsbinns]

Description of the problem

Docstring of set_eeg_reference says it supports list of str | str | dict for ref_channels. However, str only works for "average" or "REST". Trying to pass a string of a channel name leads to an error that is a little obscure.

If you want to set the reference to a single channel, this has to be done as a list with a single string entry. It's a trivial fix on the user end, but with the current error, it might not be immediately obvious what the fix is, especially for newer users.

I think at the very least, a note should be added to the docstring that channel names need to be provided as a list, even for a single channel.

It would also be nice to actually catch the problem and raise a less obtuse error message. But at that point, the checks would be in place to just support a single channel name by catching strings which are not "average" or "REST", and putting this in a list internally.

Steps to reproduce

import os

import mne

sample_data_folder = mne.datasets.sample.data_path()
sample_data_raw_file = os.path.join(
    sample_data_folder, "MEG", "sample", "sample_audvis_raw.fif"
)
raw = mne.io.read_raw_fif(sample_data_raw_file, verbose=False)
raw.crop(tmax=60).load_data()

raw.set_eeg_reference("A1")

Link to data

No response

Expected results

Passing a string of a channel name should be allowed, or channel names always needing to be provided in lists (even for a single channel) should be noted in the docs.

Actual results

Traceback (most recent call last):
  File "/home/tsbinns/GitHub/mne-python/src/flowns_eeg_project/preprocessing/test.py", line 12, in <module>
    raw.set_eeg_reference("A1")
    ~~~~~~~~~~~~~~~~~~~~~^^^^^^
  File "<decorator-gen-130>", line 12, in set_eeg_reference
  File "/home/tsbinns/GitHub/mne-python/.pixi/envs/default/lib/python3.13/site-packages/mne/channels/channels.py", line 332, in set_eeg_reference
    return set_eeg_reference(
           ~~~~~~~~~~~~~~~~~^
        self,
        ^^^^^
    ...<5 lines>...
        joint=joint,
        ^^^^^^^^^^^^
    )[0]
    ^
  File "<decorator-gen-127>", line 12, in set_eeg_reference
  File "/home/tsbinns/GitHub/mne-python/.pixi/envs/default/lib/python3.13/site-packages/mne/_fiff/reference.py", line 489, in set_eeg_reference
    return _apply_reference(inst, ref_channels, ch_sel, forward, ch_type=ch_type)
  File "/home/tsbinns/GitHub/mne-python/.pixi/envs/default/lib/python3.13/site-packages/mne/_fiff/reference.py", line 157, in _apply_reference
    ref_to = _check_before_reference(inst, ref_from, ref_to, ch_type)
  File "/home/tsbinns/GitHub/mne-python/.pixi/envs/default/lib/python3.13/site-packages/mne/_fiff/reference.py", line 42, in _check_before_reference
    _check_ssp(inst, ref_from + ref_to)
                     ~~~~~~~~~^~~~~~~~
TypeError: can only concatenate str (not "list") to str

Additional information

Platform             Linux-6.17.0-22-generic-x86_64-with-glibc2.39
Python               3.13.13 | packaged by conda-forge | (main, Apr  8 2026, 02:00:33) [GCC 14.3.0]
Executable           /home/tsbinns/GitHub/flowns-eeg-project/.pixi/envs/default/bin/python
CPU                  12th Gen Intel(R) Core(TM) i7-12650H (16 cores)
Memory               15.3 GiB

Core
├☑ mne               1.12.1 (latest release)
├☑ numpy             2.4.4 (OpenBLAS 0.3.31.188.0 with 16 threads)
├☑ scipy             1.17.1
└☑ matplotlib        3.10.9 (backend=tkagg)

Numerical (optional)
├☑ sklearn           1.8.0
├☑ numba             0.65.1
├☑ pandas            3.0.2
├☑ h5io              0.2.5
├☑ h5py              3.16.0
└☐ unavailable       nibabel, nilearn, dipy, openmeeg, cupy

Visualization (optional)
├☑ mne-qt-browser    0.7.4
└☐ unavailable       pyvista, pyvistaqt, vtk, qtpy, ipympl, pyqtgraph, ipywidgets, trame_client, trame_server, trame_vtk, trame_vuetify

Ecosystem (optional)
├☑ mne-bids          0.18.0
├☑ mne-connectivity  0.8.1
└☐ unavailable       mne-nirs, mne-features, mne-icalabel, mne-bids-pipeline, neo, eeglabio, edfio, curryreader, mffpy, pybv, pymef, antio, defusedxml