{"record":{"id":"841c778c06f8dce6","repo":"AvaloniaUI/Avalonia","slug":"musl-doesn-t-support-rtld-deepbind","errorCode":null,"errorMessage":"musl doesn't support RTLD_DEEPBIND","messagePattern":"musl doesn't support RTLD_DEEPBIND","errorType":"exception","errorClass":"PlatformNotSupportedException","httpStatus":null,"severity":"error","filePath":"samples/XEmbedSample/HarfbuzzWorkaround.cs","lineNumber":44,"sourceCode":"\n */\n \npublic unsafe class HarfbuzzWorkaround\n{\n    [DllImport(\"libc\")]\n    static extern int dlinfo(IntPtr handle, int request, IntPtr info);\n\n    [DllImport(\"libc\")]\n    static extern IntPtr dlopen(string filename, int flags);\n\n    private const int RTLD_DI_ORIGIN = 6;\n    private const int RTLD_NOW = 2;\n    private const int RTLD_DEEPBIND = 8;\n    \n    public static void Apply()\n    {\n        if (RuntimeInformation.RuntimeIdentifier.Contains(\"musl\"))\n            throw new PlatformNotSupportedException(\"musl doesn't support RTLD_DEEPBIND\");\n        \n        var libraryPathBytes = Marshal.AllocHGlobal(4096);\n        var handle = NativeLibrary.Load(\"libHarfBuzzSharp\", typeof(HarfBuzzSharp.Blob).Assembly, null);\n        dlinfo(handle, RTLD_DI_ORIGIN, libraryPathBytes);\n        var libraryOrigin = Marshal.PtrToStringUTF8(libraryPathBytes) ?? string.Empty;\n        Marshal.FreeHGlobal(libraryPathBytes);\n        var libraryPath = Path.Combine(libraryOrigin, \"libHarfBuzzSharp.so\");\n        \n        NativeLibrary.Free(handle);\n        var forceLoadedHandle = dlopen(libraryPath, RTLD_NOW | RTLD_DEEPBIND);\n        if (forceLoadedHandle == IntPtr.Zero)\n            throw new DllNotFoundException($\"Unable to load {libraryPath} via dlopen\");\n        \n        NativeLibrary.SetDllImportResolver(typeof(HarfBuzzSharp.Blob).Assembly, (name, assembly, searchPath) =>\n        {\n            if (name.Contains(\"HarfBuzzSharp\"))\n                return dlopen(libraryPath, RTLD_NOW | RTLD_DEEPBIND);\n            return NativeLibrary.Load(name, assembly, searchPath);","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/AvaloniaUI/Avalonia/blob/11c542726898ae954a1ef668c65ec79ec92ab17d/samples/XEmbedSample/HarfbuzzWorkaround.cs#L26-L62","documentation":"HarfbuzzWorkaround.Apply reloads libHarfBuzzSharp.so with RTLD_DEEPBIND to win the symbol-resolution race with Avalonia's own Skia/HarfBuzz. RTLD_DEEPBIND is a glibc-only flag and is not implemented by musl (Alpine Linux), so the code hard-fails on musl runtimes before attempting any load.","triggerScenarios":"Calling HarfbuzzWorkaround.Apply() on a .NET runtime whose RuntimeIdentifier contains 'musl' (Alpine/musl-based images). The guard throws immediately because the workaround's mechanism (deepbind) cannot exist there.","commonSituations":"Running an Avalonia Linux app inside an Alpine Docker container or any musl-based distro; .NET musl RIDs (linux-musl-x64 / linux-musl-arm64).","solutions":["Run on a glibc-based distro (Debian/Ubuntu/Fedora) where RTLD_DEEPBIND is supported.","Use a glibc-based base image instead of an Alpine one for the app.","Skip Apply() on musl and rely on Avalonia's bundled HarfBuzz (remove the deepbind workaround).","If deepbind is required, port the workaround to a musl-compatible mechanism (RTLD_LOCAL preloading / symbol interposition)."],"exampleFix":"// before\nif (RuntimeInformation.RuntimeIdentifier.Contains(\"musl\"))\n    throw new PlatformNotSupportedException(\"musl doesn't support RTLD_DEEPBIND\");\n\n// after (no-op on musl instead of hard-failing)\nif (RuntimeInformation.RuntimeIdentifier.Contains(\"musl\"))\n    return; // deepbind workaround is glibc-only; musl uses the bundled HarfBuzz as-is","handlingStrategy":"fallback","validationCode":"// skip the workaround on musl\nif (RuntimeInformation.RuntimeIdentifier.Contains(\"musl\"))\n{ /* use bundled HarfBuzz as-is; do not call Apply() */ }","typeGuard":"static bool IsMusl() => RuntimeInformation.RuntimeIdentifier.Contains(\"musl\");","tryCatchPattern":"try { HarfbuzzWorkaround.Apply(); }\ncatch (PlatformNotSupportedException ex) when (ex.Message.Contains(\"musl\"))\n{ /* acceptable on musl; bundled HarfBuzz is used */ }","preventionTips":["Use a glibc-based image when the workaround is required.","Make Apply() a no-op on musl instead of throwing.","Confirm the host libc type before invoking the workaround."],"tags":["linux","musl","alpine","harfbuzz","dlopen","native-libs","sample"],"backgroundTag":null,"analyzedSha":"11c542726898ae954a1ef668c65ec79ec92ab17d","analyzedAt":"2026-08-13T11:57:40.261Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}