Upgrade

Beginner

Tutorial

Unlike a canister reinstall that preserves the canister identifier but no state, a canister upgrade enables you to preserve the state of a deployed canister and change the code.

For example, assume you have a dapp that manages professional profiles and social connections. If you want to add a new feature to the dapp, you need to be able to update the canister code without losing any of the previously-stored data. A canister upgrade enables you to update existing canister identifiers with program changes without losing the program state.

To preserve state when you are upgrading a canister written in Motoko, be sure to use the stable keyword to identify the variables you want to preserve. For more information about preserving variable state in Motoko, see stable variables and upgrade methods.

To upgrade a canister, first you must:

1. Edit the canister's code and save the changes.

2. Use dfx build <canister-name> to compile the code into a new Wasm module.

3. Use dfx canister install <canister-name> --mode upgrade to install the new Wasm module.

Errors related to canister upgrades

Common errors related to canister upgrades include:

• Missing upgrade option.
• Invalid upgrade option.