git-ecosystem/git-credential-manager · error · InteropException

Failed to unlock item

Error message

Failed to unlock item

What it means

During Enumerate, each locked item found by the search is unlocked with secret_item_unlock_sync; if the call does not unlock exactly one item (numUnlocked != 1), an InteropException is thrown because the credential's secret cannot be read while the item remains locked.

Solutions

1. Unlock the keyring beforehand (login to the desktop session or run seahorse and unlock 'Default keyring')
2. Ensure a prompter is available: run within a session that can show the unlock dialog, or pre-unlock via gnome-keyring-daemon --unlock
3. Catch InteropException and treat locked items as inaccessible rather than aborting enumeration
4. Check the numUnlocked value in the exception code to distinguish 0 unlocked from other counts

Example fix

// before
var cred = collection.Get("myapp", "user"); // throws while keyring locked
// after
UnlockKeyringViaPrompt(); // e.g. gnome-keyring-daemon --unlock or seahorse
var cred = collection.Get("myapp", "user");

// Cannot query lock state via this API; ensure session can prompt:
bool CanPrompt() => Environment.UserInteractive && Environment.GetEnvironmentVariable("DISPLAY") != null;

try { return collection.Get(key); }
catch (InteropException ex) when (ex.Message == "Failed to unlock item") { PromptUserToUnlockKeyring(); return collection.Get(key); }

When it happens

Trigger: GetAccounts() or Get() iterating items whose collection is locked, and the unlock prompt is cancelled, times out, or returns a count other than 1 (e.g. 0 unlocked).

Common situations: Headless/session-less environments where no unlock prompt UI can appear; user dismisses the keyring password prompt; keyring password changed or unknown.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

• Cannot use the ' ' credential backing store without a…
• Failed to search for credentials
• Failed to store credentials
• -1
• Failed to erase credentials

AI-assisted analysis of git-ecosystem/git-credential-manager@e8ce762cd0 (2026-09-11). Data as JSON: /api/errors/09b7e0225b563c73. Report an issue: GitHub.

Appendix: source

Thrown at src/Core/Interop/Linux/SecretServiceCollection.cs:111

                    {
                        var toUnlockList = new GList
                        {
                            data = (IntPtr) item,
                            next = IntPtr.Zero,
                            prev = IntPtr.Zero
                        };

                        int numUnlocked = secret_service_unlock_sync(
                            secService,
                            &toUnlockList,
                            IntPtr.Zero,
                            out _,
                            out error
                        );

                        if (numUnlocked != 1)
                        {
                            throw new InteropException("Failed to unlock item", numUnlocked);
                        }
                    }

                    credentials.Add(CreateCredentialFromItem(item));

                    itemPtr = (GList*)itemPtr->next;
                }

                return credentials;
            }
            finally
            {
                if (queryAttrs != null) g_hash_table_destroy(queryAttrs);
                if (error != null) g_error_free(error);
                if (results != null) g_list_free_full(results, g_object_unref);
            }
        }

View on GitHub (pinned to e8ce762cd0)