stride3d/stride · error · AssetException

Failed to compile a video asset, ffmpeg was not found.

Error message

Failed to compile a video asset, ffmpeg was not found.

What it means

VideoAssetCompiler needs ffmpeg to process video sources. When ToolLocator.LocateTool("ffmpeg") cannot find an executable it returns null and the compiler throws this AssetException before opening the media.

Solutions

1. Install ffmpeg and add it to PATH for the build environment
2. Make the binary executable (chmod +x) on Linux/macOS
3. Confirm with 'ffmpeg -version' in the same shell/user context the build uses
4. Add ffmpeg to the CI/docker image before running the asset build

if (ToolLocator.LocateTool("ffmpeg", ensureExecutable: true) is null)
    throw new InvalidOperationException("Install ffmpeg and add it to PATH before building video assets.");

static bool FfmpegAvailable() => ToolLocator.LocateTool("ffmpeg", ensureExecutable: true) != null;

try
{
    await CompileVideoAsync(asset);
}
catch (AssetException ex) when (ex.Message.Contains("ffmpeg was not found"))
{
    logger.Error("Install ffmpeg and ensure it is on PATH, then rebuild.");
}

When it happens

Trigger: DoCommandOverride compiles a video asset and ffmpeg is not locatable on the machine (not on PATH, missing, or not executable).

Common situations: Missing ffmpeg on dev machine or CI agent, PATH not visible to the build process, non-executable downloaded binary, container images without ffmpeg installed.

Related errors

• Failed to compile a sound asset, ffmpeg was not found.
• Failed to compile a video asset. ffmpeg failed to convert
• Failed to compile a sound asset, ffmpeg failed to convert
• No video track found in
• Failed to get HW surface format.

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

Appendix: source

Thrown at sources/engine/Stride.Assets/Media/VideoAssetCompiler.cs:86

            {
                Version = 5;
                ListSupportedCodecNames = listSupportedCodecNames;
            }

            public override IEnumerable<ObjectUrl> GetInputFiles()
            {
                yield return new ObjectUrl(UrlType.File, Parameters.SourcePathFromDisk);
            }

            /// <inheritdoc />
            protected override async Task<ResultStatus> DoCommandOverride(ICommandContext commandContext)
            {
                VideoAsset videoAsset = Parameters.Video;

                try
                {
                    // Get path to ffmpeg
                    var ffmpeg = ToolLocator.LocateTool("ffmpeg", ensureExecutable: true)?.ToOSPath() ?? throw new AssetException("Failed to compile a video asset, ffmpeg was not found.");

                    // Get absolute path of asset source on disk
                    var assetDirectory = videoAsset.Source.GetParent();
                    var assetSource = UPath.Combine(assetDirectory, videoAsset.Source);

                    //=====================================================================================
                    //Get the info from the video codec
                    
                    //Check if we need to reencode the video
                    var mustReEncodeVideo = false;
                    var sidedataStripCommand = "";

                    // check that the video file format is supported
                    if (Parameters.Platform == PlatformType.Windows && videoAsset.Source.GetFileExtension() != ".mp4")
                        mustReEncodeVideo = true;

                    //Use FFmpegMedia object (need to check more details first before I can use it)
                    VideoStream videoStream = null;

View on GitHub (pinned to 96fad776d2)