使用EncryptedSharedPreferences报错：Protocol message contained an invalid tag (zero)

问题结论 #

这个异常不是参数值问题，_androidx_security_master_key_是AndroidX Security库官方默认的主密钥别名，完全合法。异常根源在于Tink库解析Protocol Buffer格式数据时，遇到了损坏、格式不兼容或不符合预期的内容。

常见触发原因及解决方法 #

• 旧版密钥数据兼容问题：如果App之前使用过旧版本的AndroidX Security库生成密钥，升级库版本后可能出现新旧密钥格式不兼容，导致解析失败。
  • 测试环境可直接清除App存储数据，让库重新生成符合当前版本的密钥文件
  • 生产环境需编写数据迁移逻辑，将旧格式密钥转换为新版Tink兼容格式
• 多进程操作冲突：当App存在多进程同时访问EncryptedSharedPreferences时，可能导致密钥文件或加密SP文件损坏。
  • 给多进程下的SP访问逻辑加全局锁，或者避免跨进程使用EncryptedSharedPreferences
• 依赖版本冲突：项目中其他依赖引入了独立的Tink库版本，与AndroidX Security自带的Tink版本冲突，导致Protobuf解析逻辑混乱。
  • 统一Tink相关依赖版本，优先使用AndroidX Security库内置的Tink版本，可通过依赖分析工具排查冲突
• 存储IO异常：设备存储空间不足或出现硬件故障，导致密钥文件写入/读取时数据损坏。
  • 检查设备存储状态，引导用户清理空间或修复存储问题

快速验证方案 #

在测试设备上清除App的存储数据后重新运行代码，若异常消失，即可确认是旧数据损坏导致的问题。

内容的提问来源于stack exchange，提问作者Mathias Rönnlund