Troubleshooting Subnet Deployments
If you run into trouble deploying your Subnet, use this document for tips to resolve common issues.
Deployment Times Out
During a local deployment, your network may fail to start. Your error may look something like this:
[~]$ avalanche subnet deploy mySubnet
✔ Local Network
Deploying [mySubnet] to Local Network
Backend controller started, pid: 26388, output at: /Users/user/.avalanche-cli/runs/server_20221231_111605/avalanche-cli-backend
VMs ready.
Starting network...
..................................................................................
..................................................................................
......Error: failed to query network health: rpc error: code = DeadlineExceeded desc = context deadline exceeded
Avalanche-CLI only supports running one local Avalanche network at a time. If other instances of AvalancheGo are running concurrently, your Avalanche-CLI network fails to start.
To test for this error, start by shutting down any Avalanche nodes started by Avalanche-CLI.
avalanche network clean --hard
Next, look for any lingering AvalancheGo processes with:
ps aux | grep avalanchego
If any processes are running, you need to stop them before you can launch your VM with Avalanche-CLI.
If you're running a validator node on the same box you're using Avalanche-CLI, don't end any of these lingering AvalancheGo processes. This may shut down your validator and could affect your validation uptime.
Incompatible RPC Version for Custom VM
If you're locally deploying a custom VM, you may run into this error message.
[~]$ avalanche subnet deploy mySubnet
✔ Local Network
Deploying [mySubnet] to Local Network
Backend controller started, pid: 26388, output at: /Users/user/.avalanche-cli/runs/server_20221231_111605/avalanche-cli-backend
VMs ready.
Starting network...
.........
Blockchain has been deployed. Wait until network acknowledges...
..................................................................................
..................................................................................
......Error: failed to query network health: rpc error: code = DeadlineExceeded desc = context deadline exceeded
This error has many possible causes, however you should be aware of the possibility of an RPC protocol version mismatch.
AvalancheGo communicates with custom VMs over RPC using gRPC. gRPC defines a protocol specification shared by both AvalancheGo and the VM. Both components must be running the same RPC version for VM deployment to work. You can view AvalancheGo's RPC compatibility broken down by release version.
Your custom VM's RPC version is set by the version of AvalancheGo that you import. By default, Avalanche-CLI creates local Avalalanche networks that run the latest AvalancheGo release.
Here's an example with real numbers from the AvalancheGo compatibility page. If the latest AvalancheGo release is version v1.9.4, then Avalanche-CLI deploys a network with RPC version 20. For your deploy to be successful, your VM must also have RPC version 20. Because only AvalancheGo version v1.9.4 supports RPC version 20, your VM must import AvalancheGo version v1.9.4. If the latest release were v1.9.3, your VM could safely import versions v1.9.2 or v1.9.3 because both versions support RPC version 19.
If your VM has an RPC version mismatch, you have two options. First, you can update the version of
AvalancheGo you use in your VM. This is the correct long-term approach. However, there is a
short-term workaround. Avalanche-CLI supports deploying older versions of AvalancheGo by using the
--avalanchego-version flag. Both the subnet deploy
and network start commands support
setting the AvalancheGo
version explicitly. Although it's very important to keep your version of AvalancheGo up-to-date,
this workaround helps you avoid broken builds in the short term. However, you need to upgrade
to the latest AvalancheGo version when deploying publicly to the Fuji Testnet or Mainnet.
Updates to AvalancheGo's RPC version are not tied to its semantic version scheme. Minor AvalancheGo version bumps may include a breaking RPC version bump.
Fix for MacBook Air M1/M2 — ‘Bad CPU type in executable’ Error
When running avalanche subnet deploy via the Avalanche-CLI, the terminal may throw an error that
contains the following:
zsh: bad CPU type in executable:
/Users/user.name/Downloads/build/avalanchego
This is because some Macs lack support for x86 binaries. Running the following command should fix this issue:
/usr/sbin/softwareupdate --install-rosetta