{"record":{"id":"02162a4252093f14","repo":"JosefNemec/Playnite","slug":"theme-extension-is-using-unsupported-api-version","errorCode":null,"errorMessage":"Theme/Extension is using unsupported API version.","messagePattern":"Theme/Extension is using unsupported API version\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"source/Playnite/App/PlayniteApplication.cs","lineNumber":1590,"sourceCode":"                };\r\n            }\r\n            catch (Exception e) when (!PlayniteEnvironment.ThrowAllErrors)\r\n            {\r\n                logger.Error(e, $\"Failed to install addon from uri {addonId}\");\r\n            }\r\n        }\r\n\r\n        public void InstallThemeFile(string themeFile)\r\n        {\r\n            try\r\n            {\r\n                ExtensionInstaller.VerifyThemePackage(themeFile);\r\n                var desc = ExtensionInstaller.GetPackedThemeManifest(themeFile);\r\n                desc.VerifyManifest();\r\n\r\n                if (new Version(desc.ThemeApiVersion).Major != ThemeManager.GetApiVersion(desc.Mode).Major)\r\n                {\r\n                    throw new Exception(ResourceProvider.GetString(\"LOCGeneralExtensionInstallApiVersionFails\"));\r\n                }\r\n\r\n                var message = string.Format(ResourceProvider.GetString(\"LOCThemeInstallPrompt\"),\r\n                    desc.Name, desc.Author, desc.Version);\r\n                var existing = ThemeManager.GetAvailableThemes(desc.Mode).FirstOrDefault(a => a.Id == desc.Id);\r\n                if (existing != null)\r\n                {\r\n                    message = string.Format(ResourceProvider.GetString(\"LOCThemeUpdatePrompt\"),\r\n                        desc.Name, existing.Version, desc.Version);\r\n                }\r\n\r\n                if (Dialogs.ShowMessage(\r\n                        message,\r\n                        ResourceProvider.GetString(\"LOCGeneralExtensionInstallTitle\"),\r\n                        MessageBoxButton.YesNo) == MessageBoxResult.Yes)\r\n                {\r\n                    ShowAddonPerfNotice();\r\n                    ExtensionInstaller.QueuePackageInstall(themeFile);\r","sourceCodeStart":1572,"sourceCodeEnd":1608,"githubUrl":"https://github.com/JosefNemec/Playnite/blob/5911f4e964e628aa7a69c2030ab35101afa63067/source/Playnite/App/PlayniteApplication.cs#L1572-L1608","documentation":"Thrown during theme installation (InstallThemeFile) when the packed theme manifest's ThemeApiVersion major version does not match the major version returned by ThemeManager.GetApiVersion for that theme mode. Major-version mismatches indicate breaking API changes, so the theme is rejected before install.","triggerScenarios":"Installing a .ptheme whose manifest ThemeApiVersion major differs from the currently running Playnite's theme API major version. The check is `new Version(desc.ThemeApiVersion).Major != ThemeManager.GetApiVersion(desc.Mode).Major`.","commonSituations":"A theme built for an older/newer Playnite is installed after an upgrade; the user downloaded a theme from a third party targeting a different major release; ThemeApiVersion was bumped in the manifest incorrectly.","solutions":["Update Playnite to a version whose theme API major matches the theme package.","Contact the theme author for a build targeting the current theme API version.","If authoring, set ThemeApiVersion in the manifest to the major version reported by ThemeManager.GetApiVersion for the target mode."],"exampleFix":"// before\n// theme manifest declares ThemeApiVersion = \"2.0.0\" on Playnite with API major 4\n\n// after\n// set in manifest to match current host:\n//   ThemeApiVersion: \"4.0.0\"","handlingStrategy":"validation","validationCode":"var manifest = ExtensionInstaller.GetPackedThemeManifest(themeFile);\nif (new Version(manifest.ThemeApiVersion).Major != ThemeManager.GetApiVersion(manifest.Mode).Major)\n{\n    Dialogs.ShowMessage(\"Theme targets an incompatible API version.\");\n    return;\n}","typeGuard":null,"tryCatchPattern":"try { app.InstallThemeFile(themeFile); }\ncatch (Exception e) when (e.Message.Contains(\"api version\", StringComparison.OrdinalIgnoreCase))\n{ Dialogs.ShowMessage(\"Incompatible theme API version.\"); }","preventionTips":["Match theme ThemeApiVersion major to the host's ThemeManager.GetApiVersion major before packaging.","Re-check theme compatibility after every Playnite upgrade.","Surface a clear message rather than letting the raw exception propagate."],"tags":["theme","versioning","api-compat","playnite"],"backgroundTag":null,"analyzedSha":"5911f4e964e628aa7a69c2030ab35101afa63067","analyzedAt":"2026-08-13T17:38:25.713Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}