test_tensorboard_with_symlink fails on Windows without symlink privilege #21932

Bug description

test_tensorboard_with_symlink in tests/tests_pytorch/loggers/test_tensorboard.py calls os.symlink() with no guard (line 322):

os.makedirs(source, exist_ok=True)
os.symlink(source, dest)

Windows permits symlink creation only for an elevated process or with Developer Mode enabled, and neither is the default, so the test fails for any ordinary contributor running the suite locally:

OSError: [WinError 1314] A required privilege is not held by the client
Expected: the test skips where the platform cannot create symlinks. Actual: it errors, and the suite comes back red.

Why CI doesn't catch it
ci-tests-pytorch.yml does run windows-2022 — but GitHub's Windows runners hold the symlink privilege, so the test passes there. It fails only on a contributor's machine. That's the awkward part: the platform is covered by CI, and the coverage still cannot see this.

Prior art in this repo
Lightning has fixed this exact error twice, both closed as completed:

#18900 — "Symlink last checkpoint will fail on windows due to permission error"
#18969 — "Last.ckpt symlink breaking on Windows", same WinError 1314
Those were production paths. The test for a neighbouring feature still creates a bare symlink.

What version are you seeing the problem on?
Select master.

Reproduced in studio
Leave blank — this is a local Windows-only failure and a Lightning Studio runs Linux.

How to reproduce the bug
On Windows, as a normal (non-elevated) user with Developer Mode off:

git clone https://github.com/Lightning-AI/pytorch-lightning
cd pytorch-lightning
pip install -e ".[test]"
pytest tests/tests_pytorch/loggers/test_tensorboard.py
Result: 1 failed / 17 passed.

Error messages and logs
tests/tests_pytorch/loggers/test_tensorboard.py:322: in test_tensorboard_with_symlink
os.symlink(source, dest)
E OSError: [WinError 1314] A required privilege is not held by the client:
'./lightning_logs' -> './sym_lightning_logs'
Environment
OS: Windows 11 (Windows-11-10.0.26200-SP0)
Python: 3.13.15
pytorch-lightning: master, editable install
Shell: non-elevated, Developer Mode off
git config core.symlinks: false (the Windows default for a non-elevated user)
More info
Suggested fix (implemented and verified)
Guard the call and skip with a clear reason:

os.makedirs(source, exist_ok=True)
try:
    os.symlink(source, dest)
except OSError as ex:
    # Windows refuses symlink creation unless the process is elevated or
    # Developer Mode is enabled, which is not the default. CI runners hold the
    # privilege, so this only bites contributors running the suite locally.
    # Any other OSError -- a missing parent, an existing dest -- is a real
    # failure and must not be turned into a passing skip.
    if os.name == "nt" and getattr(ex, "winerror", None) == 1314:
        pytest.skip(f"Can't create symlinks: {ex}")
    raise

os and pytest are already imported in the module. The check is deliberately narrow: only WinError 1314 on Windows skips, everything else re-raises, so a genuine setup failure cannot become a passing skip.

Result on Windows: 1 failed / 17 passed → 0 failed / 17 passed.

On RunIf(skip_windows=True)
That is the house pattern and would be a one-liner here — RunIf is already imported in this module at line 29, and skip_windows is supported (_runif.py:38). I did not choose it because it would skip on all Windows, including the windows-2022 CI job where the test currently passes and provides real coverage.

Happy to switch to RunIf if you would rather have the consistency than the CI coverage — it is your call, and I will follow whichever you prefer.

Patch: patches/pytorch-lightning/0001-tests-skip-test_tensorboard_with_symlink-when-symlin.patch (applies cleanly to master as of 2026-09-06).

What version are you seeing the problem on?

master

Reproduced in studio

No response

How to reproduce the bug

Error messages and logs

# Error messages and logs here please

Environment

#- PyTorch Lightning Version (e.g., 2.6.0):
#- PyTorch Version (e.g., 2.5):
#- Python version (e.g., 3.12):
#- OS (e.g., Linux):
#- CUDA/cuDNN version:
#- GPU models and configuration:
#- How you installed Lightning(`conda`, `pip`, source):

More info

No response

cc @ethanwharris @lantiga