The BACKWARD_INCOMPATIBLE_MODULE_UPDATE error in Sui typically occurs when your upgraded Move module introduces changes that are not backward-compatible with the previously published version.

Even minor-looking changes, like updating a constant value, can trigger this if the Sui framework determines that the module layout has changed in a way that might break compatibility for clients depending on the old version.

The BACKWARD_INCOMPATIBLE_MODULE_UPDATE error occurs when your Move module changes violate Sui's backward compatibility rules during an upgrade. To fix this, ensure all existing public function signatures, struct layouts, and storage formats remain unchanged when incrementing the version. Check for modifications to public/entry functions, struct fields, or key abilities that might break existing dependencies. Use sui move verify to detect compatibility issues before deploying. If intentional breaking changes are needed, consider deploying a new package instead of upgrading.

The BACKWARD_INCOMPATIBLE_MODULE_UPDATE error means your upgrade breaks backward compatibility. Even changing a const can trigger this if it alters the module's public API or storage layout.

How to Fix:

1. Ensure Compatibility – Avoid:

   • Removing/renaming public functions or structs.
   • Changing existing struct fields (even private ones).
   • Modifying const values used in storage.

2. Test with sui move verify – Checks upgrade compatibility before publishing.

3. If Stuck:

   • Publish as a new package (not an upgrade).
   • Or keep the old version and deploy a new module.

Root Cause

You're making breaking changes that violate Sui's backward compatibility rules. Even version number changes require strict adherence to upgrade rules.

Quick Fixes

1. Ensure Structural Compatibility:

   • Never change existing public/entry function signatures
   • Never modify existing struct fields (order/type)
   • Only add new functions/structs

2. For Version Bumps:

   // Old (v1)
   const VERSION: u64 = 1;
   
   // New (v2) - Add this instead of modifying
   const VERSION_2: u64 = 2;  // Keep old constant
   

3. Required Steps:

   # 1. Verify compatibility
   sui move verify --path <your-package> --against <original-package-id>
   
   # 2. Upgrade with explicit compatibility check
   sui client upgrade --gas-budget 1000000000 --skip-compatibility-check false
   

Common Pitfalls

• Changing public/entry function parameters
• Reordering struct fields
• Removing or modifying existing constants

If Absolutely Necessary

# Force upgrade (not recommended)
sui client upgrade --skip-compatibility-check true