boost::filesystem crashes on Musl/Alpine Linux when locale environment variables are unset

[Jackarain]

On Musl-libc based systems (e.g., Alpine Linux), boost::filesystem throws a runtime exception (locale::facet::_S_create_c_locale name not valid) during path initialization if LANG or LC_ALL environment variables are missing or misconfigured.

The issue stems from default_locale() in

filesystem/src/path.cpp

Lines 1456 to 1470 in d738637

	std::locale default_locale()
	{
	#if defined(BOOST_FILESYSTEM_WINDOWS_API)
	std::locale global_loc = std::locale();
	return std::locale(global_loc, new boost::filesystem::detail::windows_file_codecvt());
	#elif defined(BOOST_FILESYSTEM_DETAIL_USE_UTF8_CODECVT_FACET)
	std::locale global_loc = std::locale();
	return std::locale(global_loc, new boost::filesystem::detail::utf8_codecvt_facet());
	#else // Other POSIX
	// ISO C calls std::locale("") "the locale-specific native environment", and this
	// locale is the default for many POSIX-based operating systems such as Linux.
	return std::locale("");
	#endif
	}

std::locale default_locale()
{
#if defined(BOOST_FILESYSTEM_WINDOWS_API)
    ...
#elif defined(BOOST_FILESYSTEM_DETAIL_USE_UTF8_CODECVT_FACET)
    std::locale global_loc = std::locale();
    return std::locale(global_loc, new boost::filesystem::detail::utf8_codecvt_facet());
#else // Other POSIX
    return std::locale(""); // 💥 Crashes here on Musl if env is invalid !!!
#endif
}

On Musl/Alpine, std::locale("") forces the C++ standard library to look up system locale files. Since Musl does not have built-in localization data generation (locale-gen), this call fails immediately with a fatal runtime error.

Suggested Solution
We need a reliable way to completely bypass std::locale("") on environment-constrained or containerized systems.

Defining BOOST_FILESYSTEM_DETAIL_USE_UTF8_CODECVT_FACET should compile out the std::locale("") path entirely and force-fallback to Boost's internal utf8_codecvt_facet, making path initialization fully independent of host environment variables.

[Lastique]

On Musl-libc based systems (e.g., Alpine Linux), boost::filesystem throws a runtime exception (locale::facet::_S_create_c_locale name not valid) during path initialization if LANG or LC_ALL environment variables are missing or misconfigured.

I think the most reasonable solution is to have the locale environment variables set e.g. to "C.UTF-8" when running on musl. Support for working locales is a basic expectation of practically any application that does IO or text formatting. Does setting the env. variables fix the exception?

I could add a compile-time detection for musl if it is always restricted to UTF-8, but it seems it doesn't provide a predefined macro to do that. Looks like the authors wanted musl to be treated as any other libc implementation, so I'm inclined to do exactly that, i.e. not add a workaround for it.

[Jackarain]

Thanks for the reply, @Lastique

I totally see your point that apps should ideally run in a well-configured environment. However, in reality, developers often cannot fully control the final deployment environment. Missing or misconfigured environment variables are extremely common in production.

The big issue here is that std::locale("") throws a runtime exception. Because boost::filesystem::path is used everywhere, this creates a highly hidden blind spot that can easily slip through testing, leading to unexpected runtime crashes or even potential DoS vulnerabilities in production.

As a foundational library, Boost should ideally be robust enough to handle the absence of certain host environment configurations. It shouldn't just crash the whole application over a missing env var, especially when a perfectly fine fallback exists.

I agree that reliably auto-detecting Musl at compile-time is messy. To keep things simple and completely risk-free for you, what if we just allow manually defining BOOST_FILESYSTEM_DETAIL_USE_UTF8_CODECVT_FACET as a build flag?

This way, there is no need for complex Musl detection logic inside Boost, while developers have a way to safely bypass std::locale("") without impacting users, rather than being left helpless when they cannot configure the users' environment variables.

Would you be open to a PR that enables this manual configuration option?

[Lastique]

I can add a compile-time option to force Boost.Filesystem always use UTF-8 codecvt facet, but that option would be off by default. Which means users will have to build Boost.Filesystem with that option enabled themselves, which also means they can forget to do that and still be affected by the exception. This would help your case, but won't work as a fool-proof safeguard for a new user. I still think the right solution would be to ensure locale APIs work on the affected systems, either on the musl level or as part of default OS configuration (e.g. by setting the environment variables correctly by default).

Anyway, I will see about adding such an option after the 1.92 release. Though BOOST_FILESYSTEM_DETAIL_USE_UTF8_CODECVT_FACET is not the right name for such an option as it is an internal macro. It should probably be named BOOST_FILESYSTEM_USE_UTF8_CODECVT_FACET or something.

[Jackarain]

Thanks, @Lastique !

I really appreciate your understanding and willingness to add this option.

You are completely right that being off-by-default means new users might still encounter the exception if they aren't aware of it. However, having this option available is incredibly meaningful for developers. It ensures we are never left stuck or helpless when running into such environment constraints. When developers discover this option, they will definitely marvel at how thoroughly well-thought-out the Boost library is in handling every corner case!