SubtitleEdit/subtitleedit · critical · InvalidOperationException

Failed to initialize mpv: {_mpvPlayer.GetErrorString(err)}

Error message

Failed to initialize mpv: {_mpvPlayer.GetErrorString(err)}

What it means

InvalidOperationException: mpv_initialize returned a negative error code after options were applied; the message embeds mpv's own error string via GetErrorString. Core mpv initialization failed before rendering could start.

Source

Thrown at src/ui/Logic/VideoPlayers/LibMpvDynamic/LibMpvDynamicNativeControl.cs:259

        else
        {
            _mpvPlayer.SetOptionString("vo", "gpu");
        }

        _mpvPlayer.SetOptionString("sid", "no");
        _mpvPlayer.SetOptionString("keep-open", "always");
        _mpvPlayer.SetOptionString("background-color", "#000000");

        if (OperatingSystem.IsLinux())
        {
            _mpvPlayer.SetOptionString("idle", "yes");
            _mpvPlayer.SetOptionString("force-window", "yes");
        }

        err = _mpvPlayer.Initialize();
        if (err < 0)
        {
            throw new InvalidOperationException($"Failed to initialize mpv: {_mpvPlayer.GetErrorString(err)}");
        }

        Dispatcher.UIThread.Post(() =>
        {
            Cursor = new Cursor(StandardCursorType.Arrow);
            PlatformCursorManager.ForceArrowCursor();
        }, DispatcherPriority.Background);
    }

    private static string GetWindowIdString(IntPtr handle)
    {
        if (OperatingSystem.IsWindows())
        {
            return handle.ToString();
        }
        else if (OperatingSystem.IsLinux())
        {
            return handle.ToString();

View on GitHub (pinned to 17a9f07487)

Solutions

1. Read the mpv error string in the message to identify the precise init failure.
2. Install or reinstall a libmpv build matching the expected version, plus platform codecs/GPU drivers.
3. Try an alternate video output (e.g. switch from a GPU vo to the libmpv/software vo).
4. Clear any stale mpv config/cache and reset option overrides.

Example fix

// before
err = _mpvPlayer.Initialize();
if (err < 0) throw new InvalidOperationException($"Failed to initialize mpv: {_mpvPlayer.GetErrorString(err)}");

// after
err = _mpvPlayer.Initialize();
if (err < 0)
{
    logger.LogError("mpv init failed: {Msg}", _mpvPlayer.GetErrorString(err));
    await SwitchToSoftwareRenderingAsync();
}

if (!IsLibMpvAvailable() || !LibMpvMeetsMinVersion(MIN_MPV))
{
    logger.LogWarning("libmpv missing/outdated; video disabled");
    DisableVideoFeature();
    return;
}

try { InitializeMpv(); }
catch (InvalidOperationException ex)
{
    logger.LogError("mpv init failed: {Msg}", ex.Message);
    await SwitchToSoftwareRenderingAsync();
}

When it happens

Trigger: Missing system codecs or GPU drivers, conflicting mpv option values, a libmpv ABI/version mismatch, no display server on Linux (X/Wayland absent), GPU initialization failure, or stale options carried over from a prior failed load.

Common situations: A fresh machine without video codec packs, a VM/headless environment lacking GPU acceleration, a libmpv upgrade that invalidated option strings, or Wayland quirks.

Related errors

• GetErrorString(err)
• Failed to initialize mpv: {_mpvContext.GetErrorString(err)}
• Failed to initialize mpv: {_mpvContext.GetErrorString(err)}
• Failed to initialize mpv: {player.GetErrorString(err)}
• MPV delegates not loaded for software rendering.

AI-assisted analysis of SubtitleEdit/subtitleedit@17a9f07487 (2026-08-13). Data as JSON: /api/errors/2a7466fe41518c65. Report an issue: GitHub.