Solana Candy Machine v3铸造NFT时遭遇BorshIoError问题求助

错误日志 #

mint failed: SendTransactionError: Simulation failed. 
Message: Transaction simulation failed: Error processing Instruction 2: Failed to serialize or deserialize account data: Unknown. 
Logs: 
[
  "Program log: Instruction: MintV2",
  "Program 11111111111111111111111111111111 invoke [2]",
  "Program 11111111111111111111111111111111 success",
  "Program CndyV3LdqHUfDLmE5naZjVN8rBZz4tqhdefbAnjHG3JR invoke [2]",
  "Program log: Instruction: MintV2",
  "Program log: ProgramError occurred. Error Code: BorshIoError(\"Unexpected variant index: 1\"). Error Number: 64424509440. Error Message: IO Error: Unexpected variant index: 1.",
  "Program CndyV3LdqHUfDLmE5naZjVN8rBZz4tqhdefbAnjHG3JR consumed 35507 of 748405 compute units",
  "Program CndyV3LdqHUfDLmE5naZjVN8rBZz4tqhdefbAnjHG3JR failed: Failed to serialize or deserialize account data: Unknown",
  "Program Guard1JwRhJkVH6XZhzoYxeBVQe872VH6QggF4BWmS9g consumed 86802 of 799700 compute units",
  "Program Guard1JwRhJkVH6XZhzoYxeBVQe872VH6QggF4BWmS9g failed: Failed to serialize or deserialize account data: Unknown"
]

错误原因分析 #

这个BorshIoError("Unexpected variant index: 1")本质是Borsh序列化/反序列化时，客户端传递的变体类型索引与合约期望的不匹配，常见触发场景：

1. 依赖版本不一致：客户端SDK（如@metaplex-foundation/js、Umi）和部署的Candy Machine v3合约版本不兼容，导致指令数据的结构定义错位。
2. Candy Machine账户数据版本冲突：部署Candy Machine时使用的工具版本，和当前铸造用的SDK版本不匹配，账户存储的变体结构与SDK序列化逻辑不符。
3. Guard配置序列化错误：启用的Guard类型在SDK和合约中的变体索引定义不一致，比如某类Guard在新版本中调整了索引位置。

解决步骤 #

• 对齐所有Metaplex依赖版本：确保项目中所有Metaplex相关依赖（包括CLI、SDK、合约包）使用完全一致的版本，不要混合新旧版本。例如，如果你用最新的Candy Machine v3合约地址，就必须搭配对应的最新SDK版本。
• 重新部署Candy Machine：如果之前是用旧版本工具部署的Candy Machine，建议销毁旧实例并重新部署（提前备份配置和资产），确保账户数据结构与当前SDK兼容。
• 验证Guard配置：检查代码中的Guard配置，确保每个Guard的类型和参数都符合当前SDK的定义。可以用Metaplex官方CLI重新生成Guard配置，再同步到代码中，避免手动构造错误。
• 清理依赖缓存并重装：删除本地的node_modules、package-lock.json（或yarn.lock）文件，重新执行npm install或yarn install，彻底清除版本混杂的依赖。
• 使用SDK原生方法构造铸造指令：不要手动拼接MintV2指令数据，直接使用SDK提供的封装方法（如metaplex.candyMachines().builders().mint()），确保序列化逻辑与合约完全匹配。

内容的提问来源于stack exchange，提问作者hans