Linux / WSL Troubleshooting Guide

This is the full troubleshooting guide behind the Linux / WSL entry in the FAQ (Q&A). It is for users running ZCode for Linux on a Linux desktop or inside Windows WSLg. If the AppImage fails to start, the browser login does not return to ZCode, the CJK input method does not work, or the first CJK character does not appear under WSLg, walk through the checks below.

Recommended Setup

• Start ZCode as a regular user. Do not launch it with sudo.
• Pick either the deb package or the AppImage — installing both can make them overwrite each other's system URL handler.
• If you use the AppImage, keep it at a fixed path (for example ~/Applications/ZCode.AppImage) and do not move it before or after logging in.
• Under WSLg, launch both ZCode and the browser from the same WSL/Linux environment.
• For CJK input, use the IBus or Fcitx5 setup already configured on your system.

AppImage Fails to Start

Missing libfuse2

Some newer Linux distributions ship only FUSE 3 by default, while the AppImage may require libfuse.so.2. Typical error:

dlopen(): error loading libfuse.so.2
AppImages require FUSE to run.

On Ubuntu / Debian, try:

sudo apt update
sudo apt install libfuse2

If your distribution's repository does not provide libfuse2, follow the official documentation of your distribution to install a FUSE 2 compatibility package.

Nothing happens when clicking the icon

If nothing happens when launching from the application menu, start it once from a terminal to see the actual error:

~/Applications/ZCode.AppImage

We recommend using the deb package when possible.

NVIDIA / GPU startup issues

If the terminal shows GPU-process, NVIDIA, or rendering-related errors, try starting with software rendering:

~/Applications/ZCode.AppImage \
  --disable-gpu \
  --disable-software-rasterizer \
  --use-gl=swiftshader

If it still fails, temporarily add --no-sandbox to verify:

~/Applications/ZCode.AppImage \
  --no-sandbox \
  --disable-gpu \
  --disable-software-rasterizer \
  --use-gl=swiftshader

--no-sandbox should only be used for diagnosis or as a temporary workaround. For long-term use, prefer the deb package.

Recommended AppImage Placement

Keep the AppImage in a fixed directory:

mkdir -p ~/Applications
mv ~/Downloads/ZCode*.AppImage ~/Applications/ZCode.AppImage
chmod +x ~/Applications/ZCode.AppImage

Then always launch from the fixed path:

~/Applications/ZCode.AppImage

If you need fixed launch flags, create a simple launcher script:

cat > ~/Applications/zcode-launcher.sh << 'EOF'
#!/usr/bin/env bash
exec "$HOME/Applications/ZCode.AppImage" \
  --disable-gpu \
  --disable-software-rasterizer \
  --use-gl=swiftshader \
  "$@"
EOF
chmod +x ~/Applications/zcode-launcher.sh

Then use:

~/Applications/zcode-launcher.sh

If your environment only starts with --no-sandbox, you can temporarily add it to the launcher script.

Login Does Not Return to ZCode

After you finish logging in, the browser needs to hand the result back to ZCode. If the system does not associate the zcode:// scheme with ZCode correctly, or the running version differs from the one registered with the system, the browser login may complete without ZCode reacting.

First confirm ZCode is running as a regular user:

id -u

If the output is 0, you are running as root. Close ZCode and restart it as a regular user.

Then check whether the system can resolve ZCode's URL handler:

xdg-mime query default x-scheme-handler/zcode

Normally you should see a ZCode-related desktop file, for example:

zcode.desktop

If there is no output, or the output is clearly not ZCode, restart ZCode once. AppImage users should restart from the fixed path:

~/Applications/ZCode.AppImage

Then run the check again:

xdg-mime query default x-scheme-handler/zcode

AppImage login callback notes

The following situations often break the login callback:

• The AppImage was moved, renamed, or deleted after starting.
• Both the deb package and the AppImage are installed.
• The AppImage was previously launched with sudo.
• The system is still associated with an older ZCode version.
• Your launch method relies on special flags, but the system handler does not use the same flags.

Suggested fix:

1. Close all ZCode windows.
2. Move the AppImage to a fixed directory.
3. Restart ZCode from the fixed path.
4. Re-check the system handler:

xdg-mime query default x-scheme-handler/zcode

If you use a custom launcher script, also confirm the desktop file points to it:

grep -n "Exec=" ~/.local/share/applications/zcode.desktop 2>/dev/null || true

deb package notes

If you use the deb package, avoid running the AppImage at the same time. If you used the AppImage before, close all ZCode windows first, then start the deb version from the application menu or the command line:

zcode

If login still does not return to ZCode, send us the output of the following commands through the feedback channels:

xdg-mime query default x-scheme-handler/zcode
ps -ef | grep -i '[Z]Code' || true

Input Method Not Working

If you can only type English in ZCode, it is usually related to the input method environment of the current Linux/WSLg session. First confirm the input method service is running:

echo "$GTK_IM_MODULE"
echo "$QT_IM_MODULE"
echo "$XMODIFIERS"
ibus engine 2>/dev/null || true
fcitx5-remote 2>/dev/null || true

IBus users

Try launching ZCode from a shell where IBus is configured:

export GTK_IM_MODULE=ibus
export QT_IM_MODULE=ibus
export XMODIFIERS=@im=ibus
ibus-daemon -drx
~/Applications/ZCode.AppImage

If you use the deb package, replace the last line with:

zcode

Fcitx5 users

Try:

export GTK_IM_MODULE=fcitx
export QT_IM_MODULE=fcitx
export XMODIFIERS=@im=fcitx
fcitx5 -d
~/Applications/ZCode.AppImage

If you use the deb package, replace the last line with:

zcode

First CJK Character Missing under WSLg

In some WSLg + IBus environments, the first character may not appear immediately after switching to a CJK input method — you have to type an English character first before CJK input renders normally.

This is a known compatibility issue in the WSLg input method pipeline. Current workarounds:

• Launch ZCode from a shell where the input method environment variables are already configured.
• Try switching to Fcitx5.
• After switching the input method, type a placeholder character and delete it.

Information to Include When Reporting

If the steps above do not solve the problem, send us the output of the following commands through the feedback channels:

echo "WSL_DISTRO_NAME=$WSL_DISTRO_NAME"
echo "XDG_SESSION_TYPE=$XDG_SESSION_TYPE"
echo "DISPLAY=$DISPLAY"
echo "WAYLAND_DISPLAY=$WAYLAND_DISPLAY"
echo "BROWSER=$BROWSER"

id -u
which xdg-open || true
which xdg-mime || true
xdg-mime query default x-scheme-handler/zcode || true
grep -n "Exec=" ~/.local/share/applications/zcode.desktop 2>/dev/null || true
ps -ef | grep -i '[Z]Code' || true

echo "GTK_IM_MODULE=$GTK_IM_MODULE"
echo "QT_IM_MODULE=$QT_IM_MODULE"
echo "XMODIFIERS=$XMODIFIERS"
ibus engine 2>/dev/null || true
fcitx5-remote 2>/dev/null || true

If you use the AppImage, also include:

ls -l ~/Applications/ZCode.AppImage 2>/dev/null || true

Learn More