Troubleshooting

Troubleshooting

This guide covers common issues that may occur when using Nimf and their solutions.

🔍 Diagnostic Tools

1. Basic Status Check

# Check Nimf process
ps aux | grep nimf

# Check environment variables
echo "GTK_IM_MODULE: $GTK_IM_MODULE"
echo "QT_IM_MODULE: $QT_IM_MODULE"
echo "XMODIFIERS: $XMODIFIERS"

# Check input module files
ls -la /usr/lib/*/gtk-*/*/immodules/im-nimf.so
ls -la /usr/lib/*/qt*/plugins/platforminputcontexts/*nimf*

2. Debug Mode Execution

# Run Nimf in debug mode
killall nimf
G_MESSAGES_DEBUG=nimf nimf --debug

# Run applications in separate terminal
GTK_IM_MODULE=nimf gedit
QT_IM_MODULE=nimf kate

🚫 Common Issues

1. Input Method Not Working At All

Symptoms

• No Korean input at all
• No response when pressing Ctrl+Space

Solutions

Step 1: Check Environment Variables

# Add to ~/.bashrc or ~/.zshrc
export GTK_IM_MODULE=nimf
export QT_IM_MODULE=nimf
export XMODIFIERS=@im=nimf

# Apply settings
source ~/.bashrc

Step 2: Configure im-config (Ubuntu/Debian)

im-config -n nimf

Step 3: Restart Nimf

killall nimf
nimf &

2. Not Working in Specific Applications

GTK Applications (Firefox, LibreOffice, gedit, etc.)

# Check GTK input modules
ls /usr/lib/*/gtk-*/*/immodules/im-nimf.so

# Update GTK input module cache
sudo gtk-query-immodules-2.0 --update-cache
sudo gtk-query-immodules-3.0 --update-cache

# Run application
GTK_IM_MODULE=nimf firefox

Qt Applications (Kate, Konsole, VLC, etc.)

# Check Qt input modules
ls /usr/lib/*/qt*/plugins/platforminputcontexts/*nimf*

# Set Qt environment variables
export QT_IM_MODULE=nimf
export QT_QPA_PLATFORMTHEME=qt5ct  # If needed

# Run application
kate

Electron Applications (VS Code, Discord, etc.)

# Configuration for Electron applications
export GTK_IM_MODULE=nimf
export XMODIFIERS=@im=nimf

# Run VS Code
code --enable-features=UseOzonePlatform --ozone-platform=wayland

3. ibus Conflicts

Symptoms

• Input method works unstably
• Two input methods running simultaneously

Solutions

Method 1: Complete ibus Removal (Recommended)

sudo apt purge ibus
sudo apt autoremove

Method 2: Disable ibus-daemon

sudo mv /usr/bin/ibus-daemon /usr/bin/ibus-daemon.bak

Method 3: Disable ibus Service

systemctl --user mask ibus.service
systemctl --user stop ibus.service

4. Wayland Issues (v1.4.0+ Greatly Improved)

Symptoms

• Input method not working in Wayland session
• Working only in some applications

Solutions (v1.4.0+ Improvements)

Step 1: Check Enhanced Wayland Support

echo $XDG_SESSION_TYPE  # Check wayland output
nimf --version  # Check 1.4.0+ version

Step 2: Automatic Wayland Detection (v1.4.0+)

# Nimf 1.4.0+ automatically detects and optimizes for Wayland
# No additional configuration needed in most cases

# Set basic environment variables only
export GTK_IM_MODULE=nimf
export QT_IM_MODULE=nimf
export XMODIFIERS=@im=nimf

Step 3: Advanced Wayland Configuration (If Needed)

# For specific applications with issues
export WAYLAND_DISPLAY=wayland-0
export GDK_BACKEND=wayland
export QT_QPA_PLATFORM=wayland

5. Korean Input Corruption

Symptoms

• Korean characters not composing, consonants and vowels separated
• Specific consonants or vowels not inputting

Solutions

Step 1: Check Fonts

# Install Korean fonts
sudo apt install fonts-noto-cjk fonts-nanum

Step 2: Locale Settings

# Check locale
locale

# Set Korean locale
sudo locale-gen ko_KR.UTF-8
export LANG=ko_KR.UTF-8

Step 3: Check libhangul Settings

# Check libhangul data
ls -la /usr/share/libhangul/

6. Qt6 Applications Input Issues (v1.4.0+ Improved)

Symptoms

• No Korean input only in Qt6-based applications
• Qt5 applications work normally

Solutions

Step 1: Check Qt6 Input Modules

ls /usr/lib/*/qt6/plugins/platforminputcontexts/
# Check if libnimfqt6.so file exists

Step 2: Set Qt6 Environment Variables

export QT_IM_MODULE=nimf
export QT6_IM_MODULE=nimf

Step 3: Enhanced Qt6 Compatibility (v1.4.0+)

# Nimf 1.4.0+ has greatly improved Qt6 compatibility
# Works without additional configuration in most Qt6 applications

# If issues persist, restart nimf
killall nimf
nimf &

7. System Tray Icon Not Visible

GNOME

# Install GNOME Shell extension
# "TopIcons Plus" or "AppIndicator and KStatusNotifierItem Support"

KDE Plasma

# System Tray Settings → Items → Enable Nimf

XFCE

# Panel → Add Items → Notification Area

🆕 v1.4.0 Specific Troubleshooting

1. Modular Package Issues

Multilingual Input Not Working

# Check nimf-i18n package installation
dpkg -l | grep nimf-i18n  # Debian/Ubuntu
rpm -qa | grep nimf-i18n  # Fedora/openSUSE

# Install if not installed
sudo apt install nimf-i18n  # Debian/Ubuntu
sudo dnf install nimf-i18n  # Fedora

2. GTK4 Application Issues

No Input in GTK4 Apps

# Check GTK4 IM module
ls /usr/lib/*/gtk-4.0/*/immodules/im-nimf.so

# Check environment variables
echo $GTK_IM_MODULE  # Should output nimf

# Update GTK4 IM module cache
sudo gtk-query-immodules-4.0 --update-cache

3. ARM64 Platform Specific Issues

Performance Degradation on ARM64

# Check ARM64 optimized build
file /usr/bin/nimf  # Should output ARM aarch64

# Optimize memory usage
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf

📊 Performance Optimization (v1.4.0+ Improved)

1. Enhanced Startup Time (v1.4.0+)

# Startup time greatly improved in 1.4.0+
# Additional optimization only if needed:

# Disable unnecessary input engines
# Edit ~/.config/nimf/nimf.conf
[Engines]
enabled-engines=nimf-libhangul,nimf-system-keyboard

2. Memory Efficiency Improvements (v1.4.0+)

# Memory usage optimized with modular structure
# Automatic memory savings when nimf-i18n is not used

# Additional optimization
# nimf-settings → Candidate Window → Adjust maximum items

3. CPU Usage Optimization

# Disable auto-completion feature (if needed)
# nimf-settings → Korean → Disable auto-completion

🔧 Advanced Troubleshooting

1. Configuration File Corruption

# Backup and reset configuration files
mv ~/.config/nimf ~/.config/nimf.backup
killall nimf
nimf &

2. Library Dependency Issues

# Check library dependencies
ldd /usr/lib/*/gtk-*/*/immodules/im-nimf.so
ldd /usr/lib/*/qt*/plugins/platforminputcontexts/libnimfqt*.so

# Install missing libraries
sudo apt install --fix-missing

3. Permission Issues

# Check configuration file permissions
ls -la ~/.config/nimf/

# Fix permissions
chmod 755 ~/.config/nimf/
chmod 644 ~/.config/nimf/*

4. Memory Leak Issues

# Check memory usage
ps aux | grep nimf | awk '{print $6}'

# Restart Nimf
killall nimf
nimf &

🐛 Bug Reports

If issues persist, please create a bug report with the following information:

Information to Collect

# System information
uname -a
lsb_release -a

# Nimf version
nimf --version

# Environment variables
env | grep -E "(GTK_IM|QT_IM|XMODIFIERS|LANG|LC_)"

# Process information
ps aux | grep nimf

# Collect logs
G_MESSAGES_DEBUG=nimf nimf --debug 2>&1 | tee nimf-debug.log

Submit Bug Report

• GitHub Issues: https://github.com/hamonikr/nimf/issues
• HamoniKR Community: https://hamonikr.org

🌐 Language Support

• 🇺🇸 English Documentation - This page
• 🇰🇷 한국어 문서 - Korean documentation

📚 Related Documentation

• Configuration - Detailed configuration methods
• Installation Guide - Reinstallation methods
• Build Instructions - Building from source