Devolutions/UniGetUI · warning · InvalidOperationException

The backup key is required.

Error message

The backup key is required.

What it means

ValidateBackupKey is called by DownloadCloudBackupAsync and RestoreCloudBackupAsync on request.Key before doing any work. If the key is null, empty, or whitespace, it throws InvalidOperationException. The key identifies a specific machine/device backup within the gist, so a blank value is a client error.

Solutions

1. Provide a non-empty Key in the IpcCloudBackupRequest, obtained from ListCloudBackupsAsync.
2. Validate the key client-side before sending the request.
3. Default to the current machine's key (BuildGistFileKey / CurrentMachineBackupKey from GetStatusAsync) if the user did not pick one.

Example fix

// before: empty key
await IpcBackupApi.DownloadCloudBackupAsync(new IpcCloudBackupRequest { Key = "" });
// after: use the current machine key or a listed entry
var status = await IpcBackupApi.GetStatusAsync();
await IpcBackupApi.DownloadCloudBackupAsync(new IpcCloudBackupRequest { Key = status.CurrentMachineBackupKey });

if (string.IsNullOrWhiteSpace(request.Key))
{
    var status = await IpcBackupApi.GetStatusAsync();
    request.Key = status.CurrentMachineBackupKey;
}

static bool HasBackupKey(string? key) => !string.IsNullOrWhiteSpace(key);

try { await IpcBackupApi.DownloadCloudBackupAsync(request); }
catch (InvalidOperationException ex) when (ex.Message.Contains("backup key is required"))
{ /* client must supply a key */ }

When it happens

Trigger: An IPC client sends a DownloadCloudBackupAsync or RestoreCloudBackupAsync request with Key unset (null), empty string, or whitespace. This is purely a client-side validation failure before any GitHub API call.

Common situations: The client omitted the Key field in the request JSON. The key was read from a config that had no value. A UI form submitted without selecting a backup entry. A programmatic caller forgot to populate the key.

Related errors

• Exactly one of content or path must be supplied when…
• The cloud backup \" \" was not found.
• maintenance actions can only run against the manager.
• GitHub authentication is required for cloud backups.
• No cloud backups are available for the current account.

AI-assisted analysis of Devolutions/UniGetUI@9b1d7d0eab (2026-08-13). Data as JSON: /api/errors/bd3202b28db94b31. Report an issue: GitHub.

Appendix: source

Thrown at src/UniGetUI.Interface.IpcApi/IpcBackupApi.cs:561

            isPublic: false,
            new Dictionary<string, string> { ["- UniGetUI Package Backups"] = ReadMeContents }
        );
    }

    private static string BuildGistFileKey()
    {
        string deviceUser = (Environment.MachineName + "\\" + Environment.UserName).Replace(
            " ",
            string.Empty
        );
        return PackageBackupStartingKey + " " + deviceUser;
    }

    private static string ValidateBackupKey(string key)
    {
        if (string.IsNullOrWhiteSpace(key))
        {
            throw new InvalidOperationException("The backup key is required.");
        }

        return key;
    }

    private static PendingGitHubDeviceFlow GetPendingGitHubDeviceFlow()
    {
        lock (GitHubAuthLock)
        {
            return _pendingGitHubDeviceFlow
                ?? throw new InvalidOperationException(
                    "No GitHub device flow is pending. Start sign-in first."
                );
        }
    }

    private static void ClearPendingGitHubDeviceFlow()
    {

View on GitHub (pinned to 9b1d7d0eab)