Post

"Error: Invalid file name. Only characters on the basic multilingual plane are supported." What do you think this error message means? I ran into it recently while #debugging a migration of several hundred thousand documents. Here's what I learned: (1/4)

jhale.devHow to detect Unicode characters outside the Basic Multilingual PlaneTL;DR 1 2 def is_on_basic_multilingual_plane(char): return int(char.encode().hex(), 16) <= int("FFFF", 16)

12/5/25, 3:16 pm0 reposts0 likes

Joseph Hale

@thehale.dev

12 May 2025

It turns out that the Basic Multilingual Plane refers to the part of the #Unicode specification which encodes all the most common characters used across the world. It's the first of 17 different planes of characters! (2/4)

Joseph Hale

@thehale.dev

12 May 2025

Notably, the basic plane does not include emojis -- those are in the Supplementary Multilingual Plane. So, the error is effectively saying, "we don't support emojis in filenames". 😭 (3/4)

Joseph Hale

@thehale.dev

12 May 2025

Once I had figured that out, it wasn't too hard to write a script to replace/remove emojis from the migrated document names. To see the code and even more details, check out my full blog post: jhale.dev/posts/detect... (4/4)

jhale.devHow to detect Unicode characters outside the Basic Multilingual PlaneTL;DR 1 2 def is_on_basic_multilingual_plane(char): return int(char.encode().hex(), 16) <= int("FFFF", 16)