Skip to main content

IC SDK troubleshooting

Beginner

This section provides information to help you troubleshoot and resolve or work around common issues that are related to the following tasks:

  • Downloading and installing the IC SDK.

  • Creating, building, or deploying canisters.

  • Using the IC SDK.

  • Running the local replica.

Migrating an existing project​

Currently, there is no automatic migration or backward compatibility for any projects that you might have created using previous versions of the IC SDK. After upgrading to the latest version, you might see error or failure messages if you attempt to build or install a project created with a previous version of the IC SDK.

In many cases, however, you can continue to work with projects from a previous release by manually changing the dfx setting in the dfx.json configuration file, then rebuilding the project to be compatible with the version of the IC SDK you have currently installed.

For example, if you have a project that was created with IC SDK version 0.8.0, open the dfx.json file in a text editor and change the dfx setting to the latest version or remove the section entirely.

Restarting the local replica​

In some cases, starting the local replica fails due to stale state. If you encounter issues when running dfx start to start the local replica:

  • Step 1: Interrupt the local replica process through Ctrl+C if necessary, then stop the local replica:​

dfx stop

  • Step 2: If not all dfx processes can be stopped, forcibly end them:​

dfx killall

  • Step 3: Restart the local replica in a clean state by running the following command:​

dfx start --clean --background

The --clean option removes checkpoints and stale state information from your project’s cache so that you can restart the local replica and web server processes in a clean state.

Resetting the state information by running dfx start --clean removes your existing canisters and new canister IDs may differ from old ones.

  • Step 4: Recreate your canisters:​

dfx canister create --all
dfx build
dfx canister install --all

Removing the canisters directory​

If you run into problems building or deploying canisters after successfully connecting to ICP and registering canister identifiers, you should remove the canisters directory before attempting to rebuild or redeploy the canisters.

You can remove the canisters directory for a project by running the following command in the project’s root directory:

rm -rf ./.dfx/* canisters/*

Reinstalling dfx​

Some bugs can be addressed by uninstalling and reinstalling the IC SDK:

~/.cache/dfinity/uninstall.sh && sh -ci "$(curl -sSL https://internetcomputer.org/install.sh)"

If you have modified the location of the IC SDK binary (the binary is titled dfx), you might want run the following command to uninstall the version of the IC SDK that is in your PATH, then reinstall the latest version of the IC SDK:

rm -rf ~/.cache/dfinity && rm $(which dfx) && sh -ci "$(curl -sSL https://internetcomputer.org/install.sh)"

Xcode prerequisite​

For macOS environments, you should have Developer Command Line Tools installed if you want to create a Git repository for your project.

You can check whether you have the developer tools installed by running xcode-select -p. You can install the developer tools by running xcode-select --install.

Memory leak​

Fixing memory leaks is an ongoing process. If you encounter any error messages related to memory leaks, you should do the following:

  • Step 1: Run dfx stop to stop currently running processes.​

  • Step 2: Uninstall the IC SDK to prevent further degradation.​

  • Step 3: Re-install the IC SDK​

  • Step 4: Run dfx start to restart replica processes.​

Alternatively, you can remove the .cache/dfinity directory and re-install the latest IC SDK dfx binary:

rm -rf ~/.cache/dfinity && sh -ci "$(curl -sSL https://internetcomputer.org/install.sh)"