#495 locale.Error: unsupported locale setting

[Artur Stępniak]

I'm getting "locale.Error: unsupported locale setting" when running e.g. rst2man docs/man/openvpn3-log.1.rst | groff -Tutf8 -man

Full output:

Traceback (most recent call last):
  File "/usr/bin/rst2man", line 8, in <module>
    sys.exit(rst2man())
             ^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/docutils/core.py", line 760, in rst2man
    rst2something('manpage', 'Unix manual (troff)', 'user/manpage.html')
  File "/usr/lib/python3.12/site-packages/docutils/core.py", line 739, in rst2something
    locale.setlocale(locale.LC_ALL, '')
  File "/usr/lib/python3.12/locale.py", line 615, in setlocale
    return _setlocale(category, locale)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
locale.Error: unsupported locale setting

my locale setting:

locale
locale: Cannot set LC_CTYPE to default locale: No such file or directory
locale: Cannot set LC_MESSAGES to default locale: No such file or directory
locale: Cannot set LC_ALL to default locale: No such file or directory
LANG=szl_PL.UTF-8
LC_CTYPE="szl_PL.UTF-8"
LC_NUMERIC=pl_PL.UTF-8
LC_TIME=pl_PL.UTF-8
LC_COLLATE="szl_PL.UTF-8"
LC_MONETARY=pl_PL.UTF-8
LC_MESSAGES="szl_PL.UTF-8"
LC_PAPER=pl_PL.UTF-8
LC_NAME=pl_PL.UTF-8
LC_ADDRESS=pl_PL.UTF-8
LC_TELEPHONE=pl_PL.UTF-8
LC_MEASUREMENT=pl_PL.UTF-8
LC_IDENTIFICATION=pl_PL.UTF-8
LC_ALL=

[Günter Milde]

Thank you for the report.

The error for the locale shell command: "locale: Cannot set LC_ALL to default locale: No such file or directory" shows that on your system , the locale setup for LC_ALL is missing something or invalid. It may be related to the rather uncommon locale for Silesian Polish.

OTOH, all Docutils command line tools set up the user's default locale in the way recommended in the documentation of the "locale" standard module https://docs.python.org/3/library/locale.html#locale.setlocale. The locale value is, e.g. used for formatting with certain values in the "date" substitution directive.

A small web search shows, that "unsupported locale setting" is a quite common problem for Python apps (e.g. https://stackoverflow.com/questions/14547631/python-locale-error-unsupported-locale-setting).

The best fix would be to get a stable and complet "locale" support on your system (silencing the errors from the locale command).
As a workaround, you may experiment with export LC_ALL=C or export LC_ALL=pl_PL.UTF-8 before calling the Docutils command line tools.

OTOH, as locale settings are no core part of Docutils processing, it may be an ideo to catch the locale.Error report it as a warning and proceed with the Python default.

[Artur Stępniak]

I somehow missed that Silesian Polish is set for some options. After changing that I no longer experience the issue. This must have been set by KDE Plasma as ~/.config/plasma-localerc contained options with those values. But how the values ended up in the file is a mistery for me.

Thank you for help

[Günter Milde]

[r9974] wraps calls to locale.setlocale() in a try/except clause and reports a warning instead of failing when ther are problems in the locale setup.

[Sebastian Pipping]

While this seems fixed in Git, I have hit this issue with the latest release 0.21.2. Please consider cutting a new release with the fix. Thank you!

[Sebastian Pipping]

PS: For anyone who likes to play with the issue in isolation, a minimal reproducer is this:

# LANG='invalid value' python3 -c 'import locale; locale.setlocale(locale.LC_ALL, "")'
Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/usr/lib/python3.11/locale.py", line 627, in setlocale
    return _setlocale(category, locale)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
locale.Error: unsupported locale setting

[Günter Milde]

The fix is now in Docutils 0.22 released 2025-07-29.
Thank you for reporting.