jellyfin/jellyfin · error · NotSupportedException

The loaded archive '{archivePath}' does not appear to be a J

Error message

The loaded archive '{archivePath}' does not appear to be a Jellyfin backup as its missing the '{ManifestEntryName}'.

What it means

Thrown during RestoreBackupAsync after opening the zip archive, when zipArchive.GetEntry(ManifestEntryName) returns null. The manifest entry is Jellyfin's signature that the archive is a real FullSystemBackup output; an archive without it is treated as a foreign/incompatible zip and rejected.

Source

Thrown at Jellyfin.Server.Implementations/FullSystemBackup/BackupService.cs:106

    public async Task RestoreBackupAsync(string archivePath)
    {
        _logger.LogWarning("Begin restoring system to {BackupArchive}", archivePath); // Info isn't cutting it
        if (!File.Exists(archivePath))
        {
            throw new FileNotFoundException($"Requested backup file '{archivePath}' does not exist.");
        }

        StorageHelper.TestCommonPathsForStorageCapacity(_applicationPaths, _logger);

        var fileStream = File.OpenRead(archivePath);
        await using (fileStream.ConfigureAwait(false))
        {
            using var zipArchive = new ZipArchive(fileStream, ZipArchiveMode.Read, false);
            var zipArchiveEntry = zipArchive.GetEntry(ManifestEntryName);

            if (zipArchiveEntry is null)
            {
                throw new NotSupportedException($"The loaded archive '{archivePath}' does not appear to be a Jellyfin backup as its missing the '{ManifestEntryName}'.");
            }

            BackupManifest? manifest;
            var manifestStream = await zipArchiveEntry.OpenAsync().ConfigureAwait(false);
            await using (manifestStream.ConfigureAwait(false))
            {
                manifest = await JsonSerializer.DeserializeAsync<BackupManifest>(manifestStream, _serializerSettings).ConfigureAwait(false);
            }

            if (manifest!.ServerVersion > _applicationHost.ApplicationVersion) // newer versions of Jellyfin should be able to load older versions as we have migrations.
            {
                throw new NotSupportedException($"The loaded archive '{archivePath}' is made for a newer version of Jellyfin ({manifest.ServerVersion}) and cannot be loaded in this version.");
            }

            if (!TestBackupVersionCompatibility(manifest.BackupEngineVersion))
            {
                throw new NotSupportedException($"The loaded archive '{archivePath}' is made for a newer version of Jellyfin ({manifest.ServerVersion}) and cannot be loaded in this version.");
            }

View on GitHub (pinned to ae8723026d)

Solutions

1. Use an archive produced by BackupService.CreateBackupAsync on this Jellyfin line.
2. If migrating from an older backup format, restore on the version that created it, then re-back up and upgrade.
3. Re-download/re-copy the backup and verify its integrity (e.g. test the zip).
4. Confirm you are not pointing at a media/library archive by mistake.

Example fix

null

using var za = new ZipArchive(File.OpenRead(archivePath), ZipArchiveMode.Read);
if (za.GetEntry(ManifestEntryName) is null)
    return Error("Selected archive is not a Jellyfin backup.");

null

try { await backup.RestoreBackupAsync(path); }
catch (NotSupportedException ex) when (ex.Message.Contains("does not appear to be a Jellyfin backup"))
{ /* prompt user for a valid backup */ }

When it happens

Trigger: Pointing RestoreBackupAsync at an arbitrary .zip; at a backup made by a different/older backup mechanism; at a backup that was truncated or whose manifest entry was stripped.

Common situations: User selects a random zip thinking it is a Jellyfin backup; restore of a backup created by a much older engine that used a different manifest name; archive corrupted in transit so the central directory lacks the entry.

Related errors

• Requested backup file '{archivePath}' does not exist.
• The loaded archive '{archivePath}' is made for a newer versi
• Cannot restore backup that has no History data.
• Cannot deserialize entity '{item}'
• Years less than or equal to 0 are invalid.

AI-assisted analysis of jellyfin/jellyfin@ae8723026d (2026-08-13). Data as JSON: /api/errors/5519f8724111cd1b. Report an issue: GitHub.