JosefNemec/Playnite · error · Exception

Cannot package theme. Unsupported API version detected: {the

Error message

Cannot package theme. Unsupported API version detected: {themeApiVer}

What it means

Thrown by Themes.PackageTheme when the theme's declared ThemeApiVersion is strictly greater than the API version Toolbox supports for the theme's Mode (DesktopApiVersion or FullscreenApiVersion). This is a forward-incompatibility guard: a theme built against a newer Playnite API than the installed Toolbox cannot be safely packaged. A lower/different version only logs a warning, not an error.

Source

Thrown at source/Tools/Playnite.Toolbox/Themes.cs:192

            var manifestPath = Path.Combine(themeDirectory, PlaynitePaths.ThemeManifestFileName);
            if (!File.Exists(manifestPath))
            {
                throw new Exception($"Manifest file ({PlaynitePaths.ThemeManifestFileName}) not found!");
            }

            var extInfo = ExtensionInstaller.GetThemeManifest(manifestPath);
            if (extInfo.Id.IsNullOrEmpty())
            {
                throw new Exception("Cannot package theme, ID is missing!");
            }

            extInfo.VerifyManifest();

            var apiVer = extInfo.Mode == ApplicationMode.Desktop ? ThemeManager.DesktopApiVersion : ThemeManager.FullscreenApiVersion;
            var themeApiVer = Version.Parse(extInfo.ThemeApiVersion);
            if (themeApiVer > apiVer)
            {
                throw new Exception($"Cannot package theme. Unsupported API version detected: {themeApiVer}");
            }
            else if (themeApiVer != apiVer)
            {
                logger.Warn("Selected theme has not been updated to the latest supported API version. Please consider updating the theme!");
                logger.Warn("https://github.com/JosefNemec/Playnite/issues/1259");
            }

            var defaultThemeDir = Path.Combine(Paths.GetThemesPath(mode), "Default");
            targetPath = Path.Combine(targetPath, $"{Common.Paths.GetSafePathName(extInfo.Id).Replace(' ', '_')}_{extInfo.Version.ToString().Replace(".", "_")}{PlaynitePaths.PackedThemeFileExtention}");
            FileSystem.PrepareSaveFile(targetPath);
            using (var zipStream = new FileStream(targetPath, FileMode.Create))
            {
                using (var zipFile = new ZipArchive(zipStream, ZipArchiveMode.Create))
                {
                    zipFile.CreateEntryFromFile(manifestPath, PlaynitePaths.ThemeManifestFileName);

                    foreach (var file in Directory.GetFiles(themeDirectory, "*.*", SearchOption.AllDirectories))
                    {

View on GitHub (pinned to 5911f4e964)

Solutions

1. Update Toolbox to a build whose ThemeManager API versions are >= the theme's ThemeApiVersion.
2. Lower theme.yaml ThemeApiVersion to match the supported API (only if the theme does not actually use newer APIs).
3. Confirm ThemeApiVersion is a valid System.Version string (e.g. `1.4.0`) — Version.Parse is strict about format.
4. Ensure Mode in theme.yaml matches the API family you intend (Desktop vs Fullscreen use different API versions).

Example fix

// before (theme.yaml)
ThemeApiVersion: 1.7.0   # Toolbox only supports up to 1.4.0

// after
ThemeApiVersion: 1.4.0

var supportedApi = mode == ApplicationMode.Desktop ? ThemeManager.DesktopApiVersion : ThemeManager.FullscreenApiVersion;
var themeApi = Version.Parse(man.ThemeApiVersion);
if (themeApi > supportedApi)
    throw new InvalidOperationException($"Theme API {themeApi} exceeds supported {supportedApi}; update Toolbox.");

When it happens

Trigger: theme.yaml ThemeApiVersion (e.g. 1.5.0) exceeds ThemeManager.DesktopApiVersion or ThemeManager.FullscreenApiVersion baked into this Toolbox build. Occurs when a theme is developed against a newer Playnite and packaged with an older Toolbox.

Common situations: Playnite upgraded but Toolbox not updated (stale Toolbox binary); theme copied from a newer Playnite into an older install; Version.Parse quirks where ThemeApiVersion in theme.yaml is malformed yet parses higher than expected.

Related errors

• Manifest file ({PlaynitePaths.ThemeManifestFileName}) not fo
• Cannot package theme, ID is missing!
• Manifest file ({PlaynitePaths.ExtensionManifestFileName}) no
• Cannot package extension, ID is missing!
• Theme changelog not found.

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