{"record":{"id":"801c0a6634ca4e55","repo":"stride3d/stride","slug":"ffmpeg-library-libraryname-was-not-loaded","errorCode":null,"errorMessage":"FFmpeg library '{libraryName}' was not loaded.","messagePattern":"FFmpeg library '(.+?)' was not loaded\\.","errorType":"exception","errorClass":"DllNotFoundException","httpStatus":null,"severity":"critical","filePath":"sources/engine/Stride.Video/FFmpeg/FFmpegUtils.cs","lineNumber":125,"sourceCode":"            foreach (var library in Libraries)\n            {\n                var name = Platform.Type == PlatformType.Windows ? library.WindowsName : library.Name;\n                libraryHandles[library.Name] = NativeLibraryHelper.PreloadLibrary(name, type);\n            }\n        }\n\n        // Resolves FFmpeg.AutoGen function pointers from libraries loaded by NativeLibraryHelper, so\n        // FFmpeg uses the same native resolution as the rest of the engine instead of ffmpeg.RootPath.\n        private sealed class StrideFunctionResolver : IFunctionResolver\n        {\n            public static readonly StrideFunctionResolver Instance = new();\n\n            public T GetFunctionDelegate<T>(string libraryName, string functionName, bool throwOnError)\n            {\n                if (!libraryHandles.TryGetValue(libraryName, out var handle) || handle == 0)\n                {\n                    if (throwOnError)\n                        throw new DllNotFoundException($\"FFmpeg library '{libraryName}' was not loaded.\");\n                    return default;\n                }\n                if (!NativeLibrary.TryGetExport(handle, functionName, out var function))\n                {\n                    if (throwOnError)\n                        throw new EntryPointNotFoundException($\"Could not find function '{functionName}' in FFmpeg library '{libraryName}'.\");\n                    return default;\n                }\n                return (T)(object)Marshal.GetDelegateForFunctionPointer(function, typeof(T));\n            }\n        }\n\n        /// <summary>\n        /// Converts a <see cref=\"AVDictionary\"/>* to a Dictionary&lt;string,string&gt;.\n        /// </summary>\n        /// <param name=\"avDictionary\">A pointer to a <see cref=\"AVDictionary\"/> struct</param>\n        /// <returns>A new dictionary containing a copy of all entries.</returns>\n        [NotNull]","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Video/FFmpeg/FFmpegUtils.cs#L107-L143","documentation":"FFmpegUtils resolves native FFmpeg functions through a library-handle cache. GetFunctionDelegate throws DllNotFoundException when the requested FFmpeg library (e.g. avcodec, avformat) has no loaded handle — i.e. the native shared library was never successfully loaded on this platform.","triggerScenarios":"Calling any FFmpeg-bound API (or GetFunctionDelegate directly with throwOnError=true) when the native library failed to load: missing DLL/SO in the output directory, wrong architecture (x86 vs x64), or EnsurePlatformSupport skipped/failed silently.","commonSituations":"Missing FFmpeg native binaries after deployment; running on Linux/macOS without the expected sonames; ASP.NET/tooling contexts where native assets aren't copied; 32-bit process loading 64-bit libs.","solutions":["Call FFmpegUtils.EnsurePlatformSupport() at startup and verify native libs are present in the output directory","Deploy the correct architecture FFmpeg binaries (match process bitness and OS)","Install system FFmpeg packages matching expected library names on Linux/macOS","Confirm the build copies FFmpeg native assets (check .csproj native asset copying / runtime store)"],"exampleFix":"// before\nmedia.Open(url); // DllNotFoundException if natives missing\n// after\nFFmpegUtils.EnsurePlatformSupport(); // throws a clear error early if natives can't load\nmedia.Open(url);","handlingStrategy":"validation","validationCode":"try { FFmpegUtils.EnsurePlatformSupport(); }\ncatch (Exception ex) { Log.Error($\"FFmpeg natives unavailable: {ex.Message}\"); }","typeGuard":null,"tryCatchPattern":"try { media.Open(url); }\ncatch (DllNotFoundException ex)\n{\n    Log.Error($\"FFmpeg native library missing: {ex.Message}\");\n    // degrade gracefully: disable video features\n}","preventionTips":["Ship native FFmpeg binaries per-RID with the app","Call EnsurePlatformSupport at startup","Match native binary architecture to process bitness"],"tags":["ffmpeg","native-library","dll-not-found","platform"],"backgroundTag":"missing-dependency","analyzedSha":"96fad776d210c221682aac1ccdf4c79dc046fc38","analyzedAt":"2026-09-14T02:59:31.279Z","contentChangedAt":"2026-09-14T02:59:31.279Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}