GNS3 client and server version mismatch: how to fix it
GNS3 refuses to connect when the app, the GNS3 VM or a remote server run different versions. Find each version, then upgrade so all match.
GNS3 starts but won't load your projects or templates, and the console shows Client version 2.2.61 is not the same as server (controller) version 2.2.59, or GNS3 version 2.2.61 is not the same as the GNS3 VM version 2.2.59. Please upgrade the GNS3 VM. The GNS3 app and one of the
servers it talks to run different releases, and GNS3 refuses to mix them.
Why it happens
GNS3 is split in parts that talk over HTTP: the app you click in, a controller that holds your projects (usually the local server on your computer), and computes that run the nodes (the local server, the GNS3 VM, or a remote Linux server). Each part checks the others' version when it connects. You can read the checks in the app's HTTP client and the controller.
Which message you see tells you which link is broken:
| Message | Who disagrees |
|---|---|
Client version X is not the same as server (controller) version Y | The app and the controller (local server or remote main server) |
GNS3 version X is not the same as the GNS3 VM version Y. Please upgrade the GNS3 VM. | The controller and the GNS3 VM |
GNS3 controller version X is not the same as compute NAME version Y | The controller and a remote server added as a compute |
For stable releases the match must be exact. The app tolerates a hotfix digit (2.2.58 with
2.2.58.1) with a warning, but the controller rejects any difference from a compute. Once the
first check fails, more errors follow, such as Error while getting templates list: and
Cannot load the GNS3 VM settings in the preferences dialog: not connected to the controller.
They all go away when the versions match.
The usual story: you installed a newer GNS3 app, and the GNS3 VM still runs the server it shipped with. The GNS3 upgrade guide is clear about it: "Your GNS3 VM version need to be the same version as the GNS3 client."
How to fix it
1. Find every version
- The app: Help, About.
- The GNS3 VM: open its window in your hypervisor. The information screen starts with
GNS3 server version:. - Any server, from your computer: query its version endpoint.
curl http://192.168.56.101:3080/v2/version
It answers with JSON such as {"local": false, "version": "2.2.59"}. On a Linux machine running
the server, gns3server --version prints the same number.
Decide which version you want. Usually that is the newest stable one, so you upgrade the side that is behind.
2. Upgrade the GNS3 VM from its menu
This is the supported way, and it keeps your images and projects.
- Shut the GNS3 VM down and take a snapshot in VMware, VirtualBox or Hyper-V. The upgrade screen itself asks you to.
- Start the VM, press Enter on the information screen, choose Upgrade and confirm.
- If the channel has several releases, the VM lists them. Pick the one that matches your app.
- Wait for the script to finish. The VM reboots at the end.
The VM downloads the release list and packages from the internet through its NAT adapter. If it
says Cannot connect to GitHub to get the GNS3 versions, fix the VM's internet access first
(choose Test in the menu to check it).
Leave Channel on the stable 2.2 channel. The menu warns that other channels are for testers.
The upgrade guide also warns against upgrading the VM with pip by hand, since that upgrades GNS3
but not its dependencies.
3. Or install the app that matches the server
If you want to keep the server as it is, for example a shared lab server, install the app of the same version instead. Every release has its Windows installer and macOS DMG on the gns3-gui releases page. Back up your projects before you install it.
4. Or replace the GNS3 VM
If the menu upgrade fails, roll back to your snapshot. Then download the GNS3 VM for your
hypervisor from the same GitHub release as your app (for example
GNS3.VM.VMware.Workstation.2.2.61.zip), import it, and point GNS3's GNS3 VM preferences at it.
To bring your images and projects across, use Migrate in the old VM's menu ("Migrate data to
another GNS3 VM").
5. Linux and remote servers
On a Linux host or a remote server installed from the GNS3 PPA, upgrade both packages together:
sudo apt update
sudo apt install gns3-gui gns3-server
If you installed with pipx, as the Linux install guide now suggests on some distributions, pin both to the same version:
pipx install --force gns3-server==2.2.61
pipx install --force gns3-gui==2.2.61
A remote server is often forgotten: upgrade it to the same version as the app and the GNS3 VM.
How to check it worked
Close GNS3 completely and open it again. The console should show no is not the same as line,
and the Servers Summary panel should show the local server and the GNS3 VM in green. Run the
curl command from step 1 against each server: every one should return the same version as Help,
About.
If it still fails
- The VM shows the right version, GNS3 still complains. Another server may still be running.
Check which server the app connects to in Edit, Preferences, Server, and query that address
with
curl. - A GNS3 VM from a different release line. A 2.2 app needs a 2.2 VM, and a 3.x app needs a 3.x VM. Download the VM from the same release page as your app.
- Apple Silicon. The ARM64 GNS3 VM was not published with every release. The newest 2.2 one is 2.2.54, so the app must be 2.2.54 too. See GNS3 on Apple Silicon.
- It connects, but the VM never goes green. That is a different problem: see Cannot connect to compute 'GNS3 VM'.
The GNS3 troubleshooting guide lists the other common errors.
A lighter way to build the lab
Part of the work here is keeping three pieces of software in step. If your lab is mostly Linux
containers, Isothrum's editor runs in the browser with no
account and nothing to install, and exports the lab as Docker Compose or Vagrant files. There is
no separate server to keep at the same version. It also opens .gns3 project files, so you can
bring an existing topology across.