stride3d/stride · critical · DllNotFoundException

FFmpeg library ' ' was not loaded.

Error message

FFmpeg library '{libraryName}' was not loaded.

What it means

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.

Solutions

1. Call FFmpegUtils.EnsurePlatformSupport() at startup and verify native libs are present in the output directory
2. Deploy the correct architecture FFmpeg binaries (match process bitness and OS)
3. Install system FFmpeg packages matching expected library names on Linux/macOS
4. Confirm the build copies FFmpeg native assets (check .csproj native asset copying / runtime store)

Example fix

// before
media.Open(url); // DllNotFoundException if natives missing
// after
FFmpegUtils.EnsurePlatformSupport(); // throws a clear error early if natives can't load
media.Open(url);

try { FFmpegUtils.EnsurePlatformSupport(); }
catch (Exception ex) { Log.Error($"FFmpeg natives unavailable: {ex.Message}"); }

try { media.Open(url); }
catch (DllNotFoundException ex)
{
    Log.Error($"FFmpeg native library missing: {ex.Message}");
    // degrade gracefully: disable video features
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Could not locate or load native library
• Could not find function
• This option is only available on Windows
• Failed to compile a sound asset, ffmpeg was not found.
• Failed to compile a sound asset, ffmpeg failed to convert

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/801c0a6634ca4e55. Report an issue: GitHub.

Appendix: source

Thrown at sources/engine/Stride.Video/FFmpeg/FFmpegUtils.cs:125

            foreach (var library in Libraries)
            {
                var name = Platform.Type == PlatformType.Windows ? library.WindowsName : library.Name;
                libraryHandles[library.Name] = NativeLibraryHelper.PreloadLibrary(name, type);
            }
        }

        // Resolves FFmpeg.AutoGen function pointers from libraries loaded by NativeLibraryHelper, so
        // FFmpeg uses the same native resolution as the rest of the engine instead of ffmpeg.RootPath.
        private sealed class StrideFunctionResolver : IFunctionResolver
        {
            public static readonly StrideFunctionResolver Instance = new();

            public T GetFunctionDelegate<T>(string libraryName, string functionName, bool throwOnError)
            {
                if (!libraryHandles.TryGetValue(libraryName, out var handle) || handle == 0)
                {
                    if (throwOnError)
                        throw new DllNotFoundException($"FFmpeg library '{libraryName}' was not loaded.");
                    return default;
                }
                if (!NativeLibrary.TryGetExport(handle, functionName, out var function))
                {
                    if (throwOnError)
                        throw new EntryPointNotFoundException($"Could not find function '{functionName}' in FFmpeg library '{libraryName}'.");
                    return default;
                }
                return (T)(object)Marshal.GetDelegateForFunctionPointer(function, typeof(T));
            }
        }

        /// <summary>
        /// Converts a <see cref="AVDictionary"/>* to a Dictionary&lt;string,string&gt;.
        /// </summary>
        /// <param name="avDictionary">A pointer to a <see cref="AVDictionary"/> struct</param>
        /// <returns>A new dictionary containing a copy of all entries.</returns>
        [NotNull]

View on GitHub (pinned to 96fad776d2)