GNS3 troubleshooting guide: fix the most common errors

GNS3 is the reference for emulating network gear, and it has a lot of moving parts: a GUI, a local server, often a GNS3 VM, a hypervisor, uBridge, Dynamips, QEMU, consoles and Wireshark. When one of them is off, the error you see is often far from the cause. This guide sends you from the symptom to the fix.

Start with four checks

Most GNS3 problems come from a handful of causes. Check these first: they take a few minutes and solve a large share of the cases.

1. The versions match. The GUI, the local server and the GNS3 VM must run the same version, to the patch number. The GNS3 documentation names a version mismatch as the cause of errors such as Unable to connect to remote server. See the version mismatch guide.
2. Hardware virtualization is on and free. VT-x or AMD-V must be enabled in the firmware, and only one hypervisor can hold it at a time. VirtualBox, VMware, KVM and Hyper-V compete for it.
3. The firewall lets GNS3 through. The GUI talks to the server over HTTP, and links between nodes on different machines use UDP. Antivirus and firewall rules often cause timeouts.
4. Your hypervisor passes virtualization through to the GNS3 VM. KVM inside the VM needs nested virtualization. GNS3 recommends VMware for the GNS3 VM; VirtualBox 6.1 and later can do it too, and GNS3 turns it on when it starts the VM. See KVM support in the GNS3 VM.

Find your error

The GNS3 VM

• KVM support available: False on the VM's screen: nested virtualization isn't reaching the VM. Fix KVM support in the GNS3 VM.
• Cannot connect to compute 'GNS3 VM', or the VM never turns green: fix the connection to the GNS3 VM.
• The GUI and the VM report different versions: match the GNS3 server and GUI versions.
• VT-x or AMD-V is not available on Windows (VERR_VMX_NO_VMX, Hyper-V, Memory integrity): free hardware virtualization on Windows.
• No VMnet interface available with VMware: create the VMnet interfaces GNS3 needs.
• A Mac with Apple Silicon (M1 to M4): what runs, and how.

Nodes and links

• Links won't start, Unable to create UDP NIO: fix UDP tunnels between nodes.
• uBridge asks for root, or permission denied on Linux: give uBridge the rights it needs.
• Dynamips routers pin a CPU core at 100%: set an Idle-PC value.
• An appliance won't import, or its image is missing: fix appliance imports.

Consoles, captures and the internet

• The console doesn't open, or telnet stops responding: get the console back.
• Wireshark doesn't start, or the capture stays empty: fix packet capture.
• Docker nodes have no internet or no DNS: give containers a way out.

Where GNS3 keeps its settings

The server reads gns3_server.conf from ~/.config/GNS3/ on Linux and macOS, and gns3_server.ini from %APPDATA%\GNS3\ on Windows. The server configuration documentation lists every location and option. Two options come up again and again:

[Qemu]
; Run QEMU without KVM acceleration (slow, but works without nested virtualization)
enable_kvm = false

Turning KVM off lets QEMU appliances boot where KVM is missing, at a large cost in speed. It is a way to keep working while you fix virtualization, not a fix in itself.

When to look beyond the fix

Many of these errors come from one design choice: GNS3 runs vendor images in a VM, inside your hypervisor, with nested virtualization. That is what lets it emulate real routers, and it is also where most of the friction lives.

If your lab doesn't need a vendor operating system in QEMU, a lab of containers skips the GNS3 VM and nested virtualization entirely. Isothrum's editor lets you draw such a lab in the browser, with switches, VLANs, routers and link conditions, and exports it as Docker Compose or Vagrant files to run with the tools you already have. It can also open your .gns3 projects. And if you need GNS3 itself, the guides above will get it running.