googleworkspace/cli · error

OS keyring failed: {}. Set GOOGLE_WORKSPACE_CLI_KEYRING_BACK

Error message

OS keyring failed: {}. Set GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file to use file storage.

What it means

In the keyring backend, reading the stored base64 AES key from the OS keyring returned an error other than NoEntry — i.e. the keyring service itself failed (no Secret Service on headless Linux, locked macOS keychain, dbus/session problems, Windows credential manager faults). The message suggests switching to the file backend, which is the supported escape hatch for headless and container environments.

Source

Thrown at crates/google-workspace-cli/src/credential_store.rs:233

                            if let Err(e) = std::fs::remove_file(key_file) {
                                if e.kind() != std::io::ErrorKind::NotFound {
                                    eprintln!(
                                        "Warning: failed to remove legacy key file at '{}': {}",
                                        key_file.display(),
                                        e
                                    );
                                }
                            }
                            return Ok(arr);
                        }
                    }
                    // Keyring contained invalid data — fall through to generate new.
                }
                Err(keyring::Error::NoEntry) => {
                    // Keyring is empty — fall through to generate new.
                }
                Err(e) => {
                    anyhow::bail!("OS keyring failed: {}. Set GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file to use file storage.", sanitize_for_terminal(&e.to_string()));
                }
            }

            // Generate a new key if keyring was empty or contained invalid data.
            let key = generate_random_key();
            let b64_key = STANDARD.encode(key);
            if let Err(e) = provider.set_password(&b64_key) {
                anyhow::bail!(
                    "Failed to set key in OS keyring: {}",
                    sanitize_for_terminal(&e.to_string())
                );
            }
            if let Err(e) = std::fs::remove_file(key_file) {
                if e.kind() != std::io::ErrorKind::NotFound {
                    eprintln!(
                        "Warning: failed to remove legacy key file at '{}': {}",
                        key_file.display(),
                        e

View on GitHub (pinned to a3768d0e82)

Solutions

1. Export GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file to store the key in a file instead of the OS keyring
2. On headless Linux, install and start a Secret Service provider (gnome-keyring + dbus) and export DBUS_SESSION_BUS_ADDRESS
3. On macOS over SSH, unlock the login keychain or switch to the file backend
4. Set the variable permanently in the environment or .env file for containers

Example fix

# before
$ gws drive files list
Error: OS keyring failed: Platform specific ... Set GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file

# after
$ export GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file
$ gws drive files list

// Probe keyring availability once at startup and select the backend explicitly
fn pick_backend() -> &'static str {
    let backend = std::env::var("GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND").unwrap_or_default();
    if backend.is_empty() && std::env::var_os("DBUS_SESSION_BUS_ADDRESS").is_none() && cfg!(target_os = "linux") {
        return "file"; // headless: avoid OS keyring entirely
    }
    "keyring"
}

When it happens

Trigger: Linux without gnome-keyring/xcwd Secret Service running (common in Docker, WSL without systemd, SSH sessions); dbus session not exported (DBUS_SESSION_BUS_ADDRESS unset); macOS keychain locked during non-interactive SSH; keyring entry corrupted by another application.

Common situations: Running gws in Docker/CI where no keyring daemon exists; first use inside an SSH session on a Mac; minimal Linux window-manager setups; hardened machines where the secret service is disabled.

Related errors

• Failed to set key in OS keyring: {}
• GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE points to {path}, but
• Decryption failed. Credentials may have been created on a di
• GOOGLE_APPLICATION_CREDENTIALS points to {adc_env}, but file
• No credentials found. Run `gws auth setup` to configure, `gw

AI-assisted analysis of googleworkspace/cli@a3768d0e82 (2026-08-16). Data as JSON: /api/errors/e6816a6898bd5035. Report an issue: GitHub.