Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Common Issues and Fixes
Machine issues (VirtualBox)
If you keep experiencing VM creation issue, install the test VirtualBox software, as it has been shown to be a viable solution for some.
- Uninstall any existing VirtualBox using the official Uninstall.tool You may need to reboot if certain kext files are not properly unloaded.
- Run Kitematic reset script
- Install VirtualBox 5.x Testing
- Install Docker Toolbox
If using Docker Toolbox on Windows, check that the account running Kitematic has set
DOCKER_TOOLBOX_INSTALL_PATH = C:\Program Files\Docker Toolbox (or whatever the actual path is). If you installed as admin, this is likely not set for your user account.
Kitematic VM Stuck at 99% or Cannot pull images
Windows Users Please make sure that your anti-virus/security/firewall allows connection to/from the VM ip 192.168.99.100
For previous windows user, assume 'default' to be 'kitematic'.
- Turn off your VM via the following terminal command
docker-machine stop docker-vm(Docker commands must be installed for this to work)
- Open your VirtualBox app and go to your Preferences (app preferences, not VM settings)
- Click on Network, and Host-Only Networks tab
- You should see a few vboxnet entries, for each one do
- Click on vboxnet entry and then click on the screw-driver icon (edit)
- Click on DHCP Server tab
- On the selected vboxnet, check if
DHCP Serveris checked - if it is, check if the
192.168.99.1- If NOT, just click Cancel and move on to the next one.
- Write down which vboxnet0, vboxnet1, vboxnet2 (however many) has the proper setting of
DHCP serverchecked and a
192.168.99.1and cancel out of the Preferences
- Select the 'default' VM
- Click Settings then Network
- Adapter 2 should be a Host-Only Adapter, and change its name to be the vboxnet you noted above.
- Click OK and close VirtualBox app
- In your terminal run:
docker-machine start default
If you were stuck at 99% you may need to regenerate the certs:
docker-machine regenerate-certs default
- You can now start Kitematic and see it working :)
If none of you vboxnet have the proper setup, you can change the one that your VM uses to have the proper server address of
If you've enabled SSH Multiplexing, it might be the cause of this problem. As pointed out in this GitHub issue disabling multiplexing for localhost resolved the issue for some people.
Virtual box port forwarding feature not working on windows - cannot establish ssh connection
If you cannot establish any ssh communication between kitematic or docker-machine and the virtualbox VM then it could be that virtualbox port forwarding is not working. To test this try using telnet on the 127.0.0.1:PORT that is used by ssh (try running with the
docker-machine -D start default debug command argument to see the failing ssh calls) and you should see the connection is blocked. If you inspect the virtualbox machine logs you will see "unknown error" in the port forwarding section. Often this is caused by unsigned drivers in the networking stack from networking software such as proxy interception. The easiest solution is uninstall the corresponding application with unsigned drivers.
Virtualbox seems to have a bug in Windows 10 and host-only adapter (mentioned above), a fix/patch exists at the following location: Windows host-only adapter creation fails due to slow background processing - The latest Windows 10 build is causing that the Virtualbox Host Only adapter, is not checking the "Virtualbox NDIS6 Bridged Networking Driver" so the default machine cannot start properly.
Another possible fix is to enable Virtualization in the Bios (VT-X) - thanks to @SkiftCreative for the tip:
- In windows 8/10 you can get there by clicking the power menu, holding [SHIFT] then hitting restart.
- Keeping [SHIFT] held until the screen changes
- Go into advanced settings, then change EUFI settings (were not changing those settings, were just getting into BIOS).
- Once in BIOS enable virtualization, then save and restart.
Make sure that the Hyper-V daemon is not running, as it will conflict with Virtualbox installation/setup.
MS Edge can't see website: Go to Start, type "Internet Options" then then the Security Tab, then click Local Intranet, then Sites. Add your Virtual Machine's IP (in this case, the Docker Host) in that list and you're golden.
In certain cases, the network driver can be disabled by some windows updates. Following the above steps to get to networking and Enabling "Virtualbox NDIS6 Bridget Networking Driver" seems to solve most of these issues. If the networking driver was disabled, VirtualBox should work just fine now (no reboot needed). Otherwise repeat for every network adapter you have (Ethernet, WiFi...) and always uncheck the NDIS6 checkbox -> apply -> check it again -> apply.
- Open network center
- Click "Change adapter settings"
- Right click your Virtualbox host-only adapter and select Properties
- Enable "Virtualbox NDIS6 Bridget Networking Driver"
Windows and Anti-virus software (thanks @wildloop)
The following software have been to block Kitematic from starting:
- Antivirus/Ad-Aware - lavasoft.com:
C:\Program Files (x86)\Lavasoft\Web Companion\TcpService\22.214.171.124\LavasoftTcpService.exe
C:\Program Files (x86)\Lavasoft\Web Companion\Application\WebCompanion.exe
- cryptoCertum Scanner - certum.pl:
C:\Program Files (x86)\Unizeto\proCertum CardManager\cryptoCertumScanner.exe
You can easily identify the software blocking Kitematic, but going through a process monitor and examining your logs:
- download and unzip Process Monitor
- stop any program that you don't need at this moment (to avoid hype)
- run Process Monitor and start capturing all events
- run Kitematic and wait for about 15 seconds
- stop capturing (magnifier icon)
- analyse logs... (use excluding/including filters, ctrl+f,...)
You will find something like this:
Kitematic.exe, Operation: ReadFile, Path: C:\Windows\System32\LavasoftTcpService64.dll Kitematic.exe, Operation: ReadFile, Path: C:\Program Files (x86)\Lavasoft\Web Companion\TcpService\126.96.36.199\LavasoftTcpService.exe ...
The above indicates that Lavasoft was preventing Kitematic from starting properly. corresponding thread: https://github.com/docker/kitematic/issues/2076#issuecomment-276613251
Kitematic uses sh for the Exec function. This can cause unwanted behavior, such as up arrows being displayed as '^[[A' in Powershell terminal. This is unavoidable, because not all docker containers have a bash shell (or csh, zsh, etc.). One way to use the bash shell, which does not have these limitations, is simply to type "bash" into the terminal each time that a new session is started.
If you want your bash shell to be the default shell for when you 'exec' into the container, then in Settings > Advanced, simply add an entry for SHELL with a value of /bin/bash. 
Note that Windows containers do not have sh so this may still be an issue without a workaround. (Open issue: https://github.com/docker/kitematic/issues/2166).
If you're a new user, you will need to verify your Dockerhub email address before installing images will work.
See Issue #789.
Cannot Download Image/Connect
This could be a simple DNS issue, try the following:
- Click on the Docker CLI button
- Type in
docker-machine ssh default
- From the terminal prompt, type in
echo "nameserver 188.8.131.52" > /etc/resolv.conf
Thanks to @kriscarle for the steps:
In a terminal, run
docker-machine rm defaultin order to remove the existing VM
Go into VirtualBox preferences and remove the host-only network. (steps shown above)
In a terminal, run
docker-machine create --driver virtualbox --virtualbox-hostonly-cidr "192.168.59.1/24" default- This will create the VM on a different subnet (
192.168.59.1/24is used as an example but any valid subnet will work.)
Move to: Common Proxy issues & Fixes
Running out of space
By default the VM is created with 20GB of disk space. If you would like to create a VM with more disk space, the following command will do just that and create a 100GB VM:
docker-machine -D create -d virtualbox --virtualbox-disk-size "100000" default
Windows ProcessBaseLayer error:
TIPS: If enabled BitLocker with "Deny write access to fixed drives not protected by BitLocker" and this error message
failed to register layer: re-exec error: exit status 1: output: ProcessBaseLayer C:\ProgramData\Docker The I/O operation has been aborted because of either a thread exit or an application request.
You need to run to PowerShell command
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Policies\Microsoft\FVE" -Name FDVDenyWriteAccess -Value 0
- TIPS: Docker deamon cannot start run pulled images, with error message;
re-exec error: exit status 1: output: ProcessBaseLayer C:\ProgramData\Docker\windowsfilter The system cannot find the path specified.
- You need to run to PowerShell command
Set-ItemProperty -Path 'HKLM:SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers' -Name VSmbDisableOplocks -Type DWord -Value 1 -Force