Fixing the Cyrillic “й” filename issue in Nextcloud (NFC vs NFD) / Исправление проблемы с буквой «й» в именах файлов Nextcloud (NFC vs NFD)
Summary (EN): Nextcloud may refuse to index files and prints will not be accessible due to incompatible encoding, often for names containing the Cyrillic “й”. Root cause: filenames arrived in NFD (decomposed) Unicode, while Nextcloud/Linux expect NFC (composed).
Кратко (RU): Nextcloud может не индексировать файлы и писать will not be accessible due to incompatible encoding, часто на именах с «й». Причина: имена пришли в NFD (разложенная форма Юникода), а Nextcloud/Linux ожидают NFC (составная форма).
1) What’s actually wrong? / В чём суть проблемы?
EN: The letter “й” can be encoded two ways:
-
NFC (composed): a single code point
U+0439 -
NFD (decomposed):
U+0438(и) +U+0306(combining breve◌̆)
Some clients (e.g., certain macOS/WebDAV flows) create NFD names. Visually identical names then have different byte sequences, so Nextcloud’s scanner flags them as incompatible and skips them.
RU: Буква «й» кодируется двумя способами:
-
NFC (составная): один код
U+0439 -
NFD (разложенная):
U+0438(и) +U+0306(диакритика «крышечка»)
Некоторые клиенты (например, отдельные сценарии macOS/WebDAV) создают имена в NFD. Визуально одинаковые имена имеют разные байты, поэтому сканер Nextcloud помечает их как несовместимые и пропускает.
Typical symptom / Типичный симптом:
Entry "files/.../Тендерный алгоритм.pdf" will not be accessible due to incompatible encoding
2) Plan to fix / План исправления
EN: Normalize all filenames on disk to NFC, then rescan the user in Nextcloud.
RU: Нормализуем все имена на диске в NFC, затем пересканируем пользователя в Nextcloud.
We’ll use:
-
occ config:system:get datadirectory— to locate the real Nextcloud data dir -
convmv— to rename entries to NFC in place (safe and repeatable) -
occ files:scan— to refresh the file cache
Мы используем: -
occ config:system:get datadirectory— найти реальный каталог данных Nextcloud -
convmv— переименовать объекты в NFC на месте (безопасно и повторяемо) -
occ files:scan— обновить кэш файлов
Run inside the Nextcloud host/container. Replace
<USER>with the NC username.
Выполняйте внутри хоста/контейнера Nextcloud. Замените<USER>на пользователя NC.
3) One-shot commands / Команды «под ключ»
EN: Set UTF-8 env, find the data directory, dry-run normalization, apply, then rescan.
RU: Включаем UTF-8, находим каталог данных, делаем «сухой прогон», применяем нормализацию и пересканируем.
# EN: Ensure UTF-8 environment (safe default)
# RU: Включаем корректную UTF-8 локаль (безопасное значение)
export LANG=C.UTF-8 LC_ALL=C.UTF-8
# EN: Get the actual Nextcloud data directory
# RU: Узнаём реальный data-dir Nextcloud
DATADIR="$(sudo -u www-data php /var/www/nextcloud/occ config:system:get datadirectory)"
FILES_DIR="$DATADIR/<USER>/files"
echo "Data dir: $DATADIR"
echo "User files: $FILES_DIR"
# EN: Install convmv if missing
# RU: Ставим convmv при необходимости
apt -y update && apt -y install convmv
# EN: Dry run — see what would be renamed to NFC (no changes yet)
# RU: «Сухой прогон» — показывает, что будет переименовано в NFC
su -s /bin/sh -c "convmv -r --nfc -f utf-8 -t utf-8 \"$FILES_DIR\"" www-data
# EN: Apply the normalization (actually renames to NFC)
# RU: Применяем нормализацию (реальные переименования в NFC)
su -s /bin/sh -c "convmv -r --nfc -f utf-8 -t utf-8 --notest \"$FILES_DIR\"" www-data
# EN: Rescan the user's files so Nextcloud updates its index
# RU: Пересканируем файлы пользователя, чтобы Nextcloud обновил индекс
sudo -u www-data php /var/www/nextcloud/occ files:scan --path="<USER>/files"
Why run as www-data? / Зачем запускать от www-data?
EN: It matches file ownership/ACLs used by Nextcloud and avoids “Permission denied”, especially when the data dir is a bind-mount.
RU: Соответствует правам Nextcloud и помогает избежать «Permission denied», особенно если data-dir примонтирован через bind-mount.
4) Optional: list non-NFC entries / Опционально: список не-NFC имён
EN: If you want to see which paths are not NFC before changing anything:
RU: Если хотите увидеть, какие пути не в NFC, до изменений:
python3 - <<'PY'
import os, unicodedata, sys, subprocess
datadir = subprocess.check_output(
["sudo","-u","www-data","php","/var/www/nextcloud/occ","config:system:get","datadirectory"],
text=True).strip()
user = "<USER>"
root = os.path.join(datadir, user, "files")
count = 0
for dp, dns, fns in os.walk(root):
for name in dns + fns:
if unicodedata.normalize('NFC', name) != name:
print(os.path.join(dp, name))
count += 1
print("TOTAL non-NFC:", count, file=sys.stderr)
PY
5) Important notes / Важные замечания
-
EN: Backups: normalization only renames paths, not contents, but always good to have a snapshot/backup.
RU: Резервные копии: нормализация меняет только имена, не содержимое, но снапшот/бэкап всегда полезен. -
EN: Collisions: if two different NFD names collapse to the same NFC,
convmvwarns. Resolve such conflicts manually.
RU: Коллизии: если два разных NFD-имени «схлопнутся» в одно NFC,convmvпредупредит. Разберите вручную. -
EN: Scope: the error string “incompatible encoding” can appear for other Unicode issues too; this guide targets the common NFD “й” case.
RU: Область: сообщение «incompatible encoding» бывает и по другим Unicode-причинам; здесь разбираем частый случай NFD для «й». -
EN: Sources: NFD names often come from macOS or certain WebDAV clients. After fixing, future uploads usually land as NFC.
RU: Источник: NFD-имена часто приходят с macOS или некоторых WebDAV-клиентов. После исправления новые загрузки обычно попадают как NFC.
6) Result / Результат
EN: After NFC normalization and a rescan, files with “й” index correctly; the incompatible encoding warnings disappear, and items show up in the web UI and via WebDAV/clients.
RU: После нормализации в NFC и пересканирования файлы с «й» корректно индексируются; предупреждения incompatible encoding исчезают, и объекты видны в веб-интерфейсе и через WebDAV/клиенты.
That’s it. / Готово.
If you want, I can package this into a Markdown file template where you only replace <USER>. / По желанию упакую это в Markdown-шаблон, где нужно лишь заменить <USER>.