JosefNemec/Playnite · error · Exception

Theme/Extension is using unsupported API version.

Error message

Theme/Extension is using unsupported API version.

What it means

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.

Source

Thrown at source/Playnite/App/PlayniteApplication.cs:1590

                };
            }
            catch (Exception e) when (!PlayniteEnvironment.ThrowAllErrors)
            {
                logger.Error(e, $"Failed to install addon from uri {addonId}");
            }
        }

        public void InstallThemeFile(string themeFile)
        {
            try
            {
                ExtensionInstaller.VerifyThemePackage(themeFile);
                var desc = ExtensionInstaller.GetPackedThemeManifest(themeFile);
                desc.VerifyManifest();

                if (new Version(desc.ThemeApiVersion).Major != ThemeManager.GetApiVersion(desc.Mode).Major)
                {
                    throw new Exception(ResourceProvider.GetString("LOCGeneralExtensionInstallApiVersionFails"));
                }

                var message = string.Format(ResourceProvider.GetString("LOCThemeInstallPrompt"),
                    desc.Name, desc.Author, desc.Version);
                var existing = ThemeManager.GetAvailableThemes(desc.Mode).FirstOrDefault(a => a.Id == desc.Id);
                if (existing != null)
                {
                    message = string.Format(ResourceProvider.GetString("LOCThemeUpdatePrompt"),
                        desc.Name, existing.Version, desc.Version);
                }

                if (Dialogs.ShowMessage(
                        message,
                        ResourceProvider.GetString("LOCGeneralExtensionInstallTitle"),
                        MessageBoxButton.YesNo) == MessageBoxResult.Yes)
                {
                    ShowAddonPerfNotice();
                    ExtensionInstaller.QueuePackageInstall(themeFile);

View on GitHub (pinned to 5911f4e964)

Solutions

1. Update Playnite to a version whose theme API major matches the theme package.
2. Contact the theme author for a build targeting the current theme API version.
3. If authoring, set ThemeApiVersion in the manifest to the major version reported by ThemeManager.GetApiVersion for the target mode.

Example fix

// before
// theme manifest declares ThemeApiVersion = "2.0.0" on Playnite with API major 4

// after
// set in manifest to match current host:
//   ThemeApiVersion: "4.0.0"

var manifest = ExtensionInstaller.GetPackedThemeManifest(themeFile);
if (new Version(manifest.ThemeApiVersion).Major != ThemeManager.GetApiVersion(manifest.Mode).Major)
{
    Dialogs.ShowMessage("Theme targets an incompatible API version.");
    return;
}

try { app.InstallThemeFile(themeFile); }
catch (Exception e) when (e.Message.Contains("api version", StringComparison.OrdinalIgnoreCase))
{ Dialogs.ShowMessage("Incompatible theme API version."); }

When it happens

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

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

Related errors

• LOC.GeneralThemePackageError
• Cannot add file to database, file not found.
• Not supported in Desktop mode.
• Cannot open plugin settings in Fullscreen mode.
• Not supported in Fullscreen mode.

AI-assisted analysis of JosefNemec/Playnite@5911f4e964 (2026-08-13). Data as JSON: /api/errors/02162a4252093f14. Report an issue: GitHub.