{"record":{"id":"2a7466fe41518c65","repo":"SubtitleEdit/subtitleedit","slug":"failed-to-initialize-mpv-mpvplayer-geterrorstri","errorCode":null,"errorMessage":"Failed to initialize mpv: {_mpvPlayer.GetErrorString(err)}","messagePattern":"Failed to initialize mpv: (.+?)","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"critical","filePath":"src/ui/Logic/VideoPlayers/LibMpvDynamic/LibMpvDynamicNativeControl.cs","lineNumber":259,"sourceCode":"        else\n        {\n            _mpvPlayer.SetOptionString(\"vo\", \"gpu\");\n        }\n\n        _mpvPlayer.SetOptionString(\"sid\", \"no\");\n        _mpvPlayer.SetOptionString(\"keep-open\", \"always\");\n        _mpvPlayer.SetOptionString(\"background-color\", \"#000000\");\n\n        if (OperatingSystem.IsLinux())\n        {\n            _mpvPlayer.SetOptionString(\"idle\", \"yes\");\n            _mpvPlayer.SetOptionString(\"force-window\", \"yes\");\n        }\n\n        err = _mpvPlayer.Initialize();\n        if (err < 0)\n        {\n            throw new InvalidOperationException($\"Failed to initialize mpv: {_mpvPlayer.GetErrorString(err)}\");\n        }\n\n        Dispatcher.UIThread.Post(() =>\n        {\n            Cursor = new Cursor(StandardCursorType.Arrow);\n            PlatformCursorManager.ForceArrowCursor();\n        }, DispatcherPriority.Background);\n    }\n\n    private static string GetWindowIdString(IntPtr handle)\n    {\n        if (OperatingSystem.IsWindows())\n        {\n            return handle.ToString();\n        }\n        else if (OperatingSystem.IsLinux())\n        {\n            return handle.ToString();","sourceCodeStart":241,"sourceCodeEnd":277,"githubUrl":"https://github.com/SubtitleEdit/subtitleedit/blob/17a9f0748781032255db3526b7215d2fb891e3af/src/ui/Logic/VideoPlayers/LibMpvDynamic/LibMpvDynamicNativeControl.cs#L241-L277","documentation":"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.","triggerScenarios":"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.","commonSituations":"A fresh machine without video codec packs, a VM/headless environment lacking GPU acceleration, a libmpv upgrade that invalidated option strings, or Wayland quirks.","solutions":["Read the mpv error string in the message to identify the precise init failure.","Install or reinstall a libmpv build matching the expected version, plus platform codecs/GPU drivers.","Try an alternate video output (e.g. switch from a GPU vo to the libmpv/software vo).","Clear any stale mpv config/cache and reset option overrides."],"exampleFix":"// before\nerr = _mpvPlayer.Initialize();\nif (err < 0) throw new InvalidOperationException($\"Failed to initialize mpv: {_mpvPlayer.GetErrorString(err)}\");\n\n// after\nerr = _mpvPlayer.Initialize();\nif (err < 0)\n{\n    logger.LogError(\"mpv init failed: {Msg}\", _mpvPlayer.GetErrorString(err));\n    await SwitchToSoftwareRenderingAsync();\n}","handlingStrategy":"try-catch","validationCode":"if (!IsLibMpvAvailable() || !LibMpvMeetsMinVersion(MIN_MPV))\n{\n    logger.LogWarning(\"libmpv missing/outdated; video disabled\");\n    DisableVideoFeature();\n    return;\n}","typeGuard":null,"tryCatchPattern":"try { InitializeMpv(); }\ncatch (InvalidOperationException ex)\n{\n    logger.LogError(\"mpv init failed: {Msg}\", ex.Message);\n    await SwitchToSoftwareRenderingAsync();\n}","preventionTips":["Bundle a libmpv build matching the expected version.","Install platform codecs and GPU drivers.","Offer a software-rendering fallback when GPU init fails.","Reset stale mpv options before initialization."],"tags":["mpv","video","native","initialization","gpu"],"backgroundTag":null,"analyzedSha":"17a9f0748781032255db3526b7215d2fb891e3af","analyzedAt":"2026-08-13T18:11:43.374Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}