troubleshooting

Troubleshooting

Q1: I get a "CRITICAL (DockerDaemonConnectionError)" permission denied error when starting a lab.

The exact error message is:

CRITICAL (DockerDaemonConnectionError) Cannot connect to Docker Daemon, this may indicate that it is not running. Error while fetching server API version: ('Connection aborted.', PermissionError(13, 'Permission denied'))

This indicates you cannot access the Docker socket. First, ensure that Docker is running properly - if you cannot run docker ps at all (even with sudo), your Docker setup is broken and needs to be fixed first. If docker ps only works with sudo, you're likely not in the Docker users group. To resolve this, add yourself to the Docker group by running:

sudo usermod -aG docker $USER

Then, log out and back in for the changes to take effect.

Q2: I can run docker ps. However, I still get a "CRITICAL (DockerDaemonConnectionError)" error.

The exact error message is (mind the difference at the end of the message):

CRITICAL (DockerDaemonConnectionError) Cannot connect to Docker Daemon, this may indicate that it is not running. Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))

If you see this error, it may indicate that you are using an unsupported version of Docker. Kathara only supports a standard "rootful" Docker installation; Docker rootless or Podman are not supported. Please ensure you are using a rootful Docker setup to resolve the issue.

Q3: I get a "CRITICAL (MachineAlreadyExistsError)

This error indicates that the lab you are trying to deploy is already running. To resolve this, first clean up the existing lab environment by running either kathara lclean or kathara wipe. After cleaning up, you can deploy the lab again.

Q4: I installed Kathara as a Python module, and now the command is gone. What happened?

Make sure that you have reactivated your Python venv. You need to do that every time you enter a new shell session. Also, ensure you properly prefix the Kathara command with python3 -m, as in python3 -m kathara.

Q5: I installed Kathara as a Python module, and the settings do not open for me.

This is a known issue with the Python module installation on Linux in version 3.7.8. The issue should be fixed with an update to version 3.7.9. Alternatively, you can manually edit the configuration file located at ~/.config/kathara.conf to change the settings, like your terminal emulator.

Q6: I get a "CRITICAL (SettingsError) Settings file is not valid: Terminal Emulator /usr/bin/xterm not valid!

This error occurs because Kathara needs the correct terminal emulator path to open device terminals after deploying a lab. If you're not using XTerm, update the terminal setting in the Kathara configuration to point to a supported terminal. The only officially supported terminals are XTerm and GNOME; you may try a custom terminal, but that is not directly supported by us.

Q7: I get a font error when using xterm:

The exact error message is:

xterm: cannot load font "-misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso10646-1"

We encountered the issue once during testing on Arch Linux. The fix recommended by the Kathara devs is to install the corresponding font package. Additionally, you need to configure a proper xterm configuration file. For more details, please refer to this post.

Q8: I get a CRITICAL (TypeError) when using tmux.

The exact error is:

CRITICAL (TypeError) decode() argument 'encoding' must be str, not None

Well... the TMUX integration is broken in version 3.7.8. This is not an issue with Kathara, but with the used libtmux library. Version 3.7.9 (released on 26.03.2025 for this very CN project) should fix this issue. For further details, please see the corresponding GitHub issue.

Q9: I, for the life of me, cannot get the terminal integration to work. What should I do?

If terminal integration isn't working, it's not a huge issue as long as your labs are starting properly (verify this using the kathara list command). When you need to connect to a device, simply use the kathara connect <device_name> command. Although this workaround might be a bit cumbersome in labs with many devices, it serves as a reliable alternative to the terminal integration.