Keychain Diagnostics

Systematic troubleshooting for Security framework failures: uniqueness constraint violations, query mismatches, data protection timing, access group entitlements, disappearing items after updates, and Mac shim behavior differences.

Overview

Core Principle: When keychain operations fail, the problem is usually:

1. Uniqueness constraint mismatch (errSecDuplicateItem) — 25%
2. Query attribute confusion (errSecItemNotFound) — 25%
3. Data protection / background timing (errSecInteractionNotAllowed) — 20%
4. Access group / entitlement mismatch (errSecMissingEntitlement) — 15%
5. Mac shim behavior differences — 10%
6. Lost items after app update (entitlement or App ID prefix change) — 5%

Always dump existing items and compare attributes BEFORE changing keychain code.

Red Flags

Symptoms that indicate keychain-specific issues: