Unicode: Emoji subfolder names don't work

[s0ren99]

Before You Continue

• This is a new, confirmed bug that has not yet been reported or documented

What Is Not Working as Documented?

(Sorry but I can't find a relevant issue.)

PhotoPrism is not showing parent folders even though the parent folders do contain valid accessible photos.

Example structure:

/originals/ins/abcbd/photo_a.jpg (Parent folder media exists here)

/originals/ins/abcbd/highlight/photo_b.jpg (Sub-folder media exists here)

/originals/ins/abcbd/highlight2/photo_c.jpg (Sub-folder media exists here)

Observed Behavior in PhotoPrism's "Folders" View after indexing:
PhotoPrism shows only:

ins/abcbd/highlight
ins/abcbd/highlight2

but NOT

ins/abcbd

The files in the missing parent folders (e.g. ins/abcbd/img001.jpg) are NOT appearing under "Search" view either, despite the files being accessible and visible via the Library > Originals view (which I would have preferred to use but unfortunately it doesn't seem to support ordering).

There are no permission issues — all files are visible in Jellyfin and on the file system, and the subfolders index normally.

This is not a flattening/hierarchy preference issue — the parent folders simply do not appear.

I'm not sure if a Complete Rescan would fix this but there are already 69140 items in Search. A Rescan would take a lot of time, which I don't want.

How Can We Reproduce It?

1. Create a folder structure where the parent folder contains both:
    Valid photos directly inside it
    Subfolders
2. Add them as Volumes
3. "START" indexing.
4. Open “Folders / Originals” view.
5. Parent folder is missing while subfolders appear.

What Behavior Do You Expect?

• The folder abcbd should appear in the “Folders / Originals” view.
• It should contain both the photos directly inside it and its subfolders (highlight, highlight2).

What Could Be the Cause?

I have no idea.

Logs, Sample Files, or Screenshots

No response

Which Software Versions Do You Use?

- PhotoPrism Architecture: AMD64
- PhotoPrism Build Number: Build 251130-b3068414c
- Database Type: MariaDB

On What Device Is PhotoPrism Installed?

Do You Use a Reverse Proxy, Firewall, VPN, or CDN?

No response

[graciousgrey]

Thank you for your report. Unfortunately I cannot reproduce this issue.
Is it possible that the photos of the folder are in the review or private section or part of a stack?

https://docs.photoprism.app/user-guide/organize/review/
https://docs.photoprism.app/user-guide/organize/private/
https://docs.photoprism.app/user-guide/organize/stacks/

[s0ren99]

Thank you for your report. Unfortunately I cannot reproduce this issue. Is it possible that the photos of the folder are in the review or private section or part of a stack?

https://docs.photoprism.app/user-guide/organize/review/ https://docs.photoprism.app/user-guide/organize/private/ https://docs.photoprism.app/user-guide/organize/stacks/

No, they are in the review or private section or part of a stack. I haven't even see any one of these sections on the toolbar.
And it's not one "folder" but all folders that have sub-folders.

[graciousgrey]

. I haven't even see any one of these sections on the toolbar.

You can find these sections on the main navigation after you have clicked on the arrow down next to Search.

[s0ren99]

. I haven't even see any one of these sections on the toolbar.

You can find these sections on the main navigation after you have clicked on the arrow down next to Search.

I see them now. Sorry I didn't read the doc carefully. Thanks for your guide.
While there are 7000+ photos in the review section, after I unclicked Quality Filter, the number of folders only increased by one with a lot of more parent folders being invisible.

[s0ren99]

. I haven't even see any one of these sections on the toolbar.

You can find these sections on the main navigation after you have clicked on the arrow down next to Search.

It seems the root cause is PhotoPrism’s folder name normalization / beautification step.

My original folder structure contains many emoji-named subfolders, e.g.:

ins/dloralyfo/
  🧝‍♀️/
  🤯/
  🪞/
  🇯🇵/
  🍑/
  🍹/
  🎃/
  🐠/
  🔗/
  <3/
  F/
  Highlights/
  More here/

PhotoPrism changes how these folders are displayed in Folders view by capitalizing, removing underscores ( _ ), and otherwise “beautifying” the folder names.
For example:

• original folder: ins/b._.rume
• shown in UI as: B. .Rume

The problem:
One of the emoji subfolders (🪞) gets normalized into the same name as its parent (Dloralyfo) in the UI.
Because of this naming collision, the actual parent folder ins/dloralyfo becomes invisible in the Folders view, and all the other emoji-named subfolders under it also disappear from the UI.

In short:

• Parent folder = Dloralyfo

• Emoji subfolder 🪞 is normalized → also becomes Dloralyfo

• Folder view hides/conflicts with the real parent, making the entire level un-navigable.

This explains why PhotoPrism was showing only some subfolders and not the parent or the rest.

It seems that folder name normalization needs to either:

1. avoid collisions with parent names, or

2. allow disabling/overriding the normalization for folders.

[lastzero]

PhotoPrism has full Unicode / UTF-8 support in its database, API, and user interface – emojis and non-ASCII characters in file and folder names should be handled correctly as long as the underlying filesystem uses a compatible encoding:

The symptoms you’re seeing are most likely caused by the filesystem or mount using a legacy / non-UTF-8 encoding, or by incorrect database charset / collation settings, as described in our MariaDB troubleshooting guide under “Unicode Support”:
https://docs.photoprism.app/getting-started/troubleshooting/mariadb/#unicode-support

PhotoPrism can only see whatever encoding the host file system and database expose inside the container.

Next step: @s0ren99, please open a terminal session in the PhotoPrism container and inspect the filesystem and locale settings (e.g. locale, mount, and ls -b in the affected directories), and verify the MariaDB charset and collation configuration. That will tell us how the filenames are actually encoded and help pinpoint where the mismatch occurs.

[s0ren99]

PhotoPrism has full Unicode / UTF-8 support in its database, API, and user interface – emojis and non-ASCII characters in file and folder names should be handled correctly as long as the underlying filesystem uses a compatible encoding:

The symptoms you’re seeing are most likely caused by the filesystem or mount using a legacy / non-UTF-8 encoding, or by incorrect database charset / collation settings, as described in our MariaDB troubleshooting guide under “Unicode Support”: https://docs.photoprism.app/getting-started/troubleshooting/mariadb/#unicode-support

PhotoPrism can only see whatever encoding the host file system and database expose inside the container.

Next step: @s0ren99, please open a terminal session in the PhotoPrism container and inspect the filesystem and locale settings (e.g. locale, mount, and ls -b in the affected directories), and verify the MariaDB charset and collation configuration. That will tell us how the filenames are actually encoded and help pinpoint where the mismatch occurs.

Thanks for the detailed response! Just to clarify: the issue I’m reporting is NOT happening in Library > Originals, where PhotoPrism displays the folder names exactly as they appear on disk.

The problem occurs specifically in Folders view, where PhotoPrism normalizes the display name (capitalizing, removing characters, or treating emoji-named folders inconsistently). For example, a real folder like:

ins/dloralyfo/🪞

shows up in Folders view with the name “Dloralyfo”, which causes conflicts and effectively hides the parent folder and other emoji-named siblings.
Another example:

So the file system itself is fine and the emoji names are correct — it’s the display normalization logic in Folders view that seems to be causing the mismatch.

Just clarifying so the investigation can focus on the Folders view name transformation rather than filesystem encoding.

[lastzero]

I understand that, but I didn't want to flood you with screenshots:

[lastzero]

We updated our MariaDB Troubleshooting Guide to provide more accurate advice and detailed examples:

• https://docs.photoprism.app/getting-started/troubleshooting/mariadb/#unicode-support

[s0ren99]

We updated our MariaDB Troubleshooting Guide to provide more accurate advice and detailed examples:

• https://docs.photoprism.app/getting-started/troubleshooting/mariadb/#unicode-support

Thanks for your guide.
compose.yaml includes --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci in photoprism and mariadb by default, so I didn't touch them.
I'm not using a DSN.
"XFS always uses UTF-8 internally on Linux"
I have fixed the Locale and ls -b is not displaying "raw UTF-8 bytes" anymore, but it still doesn't fix the folder name issue after a Complete Rescan.

---

The logs show photos getting updated or new labels:

2025-12-06 20:27:47 INFO index: updated main mp4 file ins/dloralyfo/🐠/2023-12-03...
2025-12-06 20:27:48 INFO index: updated main jpg file ins/dloralyfo/🎃/2023-10-29...

but the folders are simply not appearing in Folders view.