Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mangowm/mango/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers common issues you may encounter while using Mango and their solutions.

​
Installation Issues

Mango requires wlroots 0.19.2. Ensure you’re using the correct version:
# Clone and build wlroots 0.19.2
git clone -b 0.19.2 https://gitlab.freedesktop.org/wlroots/wlroots.git
cd wlroots
meson build -Dprefix=/usr
sudo ninja -C build install
If you have multiple wlroots versions:
pkg-config --modversion wlroots  # Check version
sudo ldconfig  # Refresh library cache
Mango requires scenefx 0.4.1 for window effects:
# Clone and build scenefx
git clone -b 0.4.1 https://github.com/wlrfx/scenefx.git
cd scenefx
meson build -Dprefix=/usr
sudo ninja -C build install
Verify installation:
pkg-config --modversion scenefx
Install all required dependencies:Arch Linux:
sudo pacman -S wayland wayland-protocols libinput libdrm libxkbcommon \
  pixman libdisplay-info libliftoff hwdata seatd pcre2 xorg-xwayland libxcb
Debian/Ubuntu:
sudo apt install libwayland-dev wayland-protocols libinput-dev libdrm-dev \
  libxkbcommon-dev libpixman-1-dev libdisplay-info-dev libliftoff-dev \
  hwdata libseatd-dev libpcre2-dev xwayland libxcb1-dev meson ninja-build
Fedora:
sudo dnf install wayland-devel wayland-protocols-devel libinput-devel \
  libdrm-devel libxkbcommon-devel pixman-devel libdisplay-info-devel \
  libliftoff-devel hwdata seatd-devel pcre2-devel xorg-x11-server-Xwayland \
  libxcb-devel meson ninja-build
Common meson issues:
# Clear build directory
rm -rf build

# Reconfigure with verbose output
meson setup build -Dprefix=/usr --wipe

# Check meson version (need >= 0.60)
meson --version

# Update if needed
pip install --user --upgrade meson

​
Startup Issues

Check common causes:
  1. Already running session:
# Check if another compositor is running
echo $WAYLAND_DISPLAY
echo $DISPLAY

# Kill existing session
pkill -x mango
  1. Permission issues:
# Check seat permissions
ls -l /dev/dri/
groups  # Should include 'video' and 'input'

# Add user to groups if missing
sudo usermod -a -G video,input $USER
# Logout and login again
  1. seatd not running:
# Start seatd
sudo systemctl enable --now seatd
sudo systemctl status seatd
  1. Check logs:
mango 2>&1 | tee ~/mango.log
This usually means Mango started but no programs launched.Quick fix: Press Alt+Return to open a terminal (default: foot)Permanent fix: Create autostart.sh:
mkdir -p ~/.config/mango
cat > ~/.config/mango/autostart.sh << 'EOF'
#!/bin/bash
# Background image
swaybg -i ~/Pictures/wallpaper.jpg &

# Status bar
waybar &

# Terminal (optional)
foot &
EOF

chmod +x ~/.config/mango/autostart.sh
From display manager:
  1. Switch to TTY (Ctrl+Alt+F3)
  2. Login
  3. Check logs:
journalctl -b -0 --user  # User session logs
journalctl -b -0 | grep mango  # System logs
Common causes:
  • Missing config file (Mango will still start)
  • Crash in autostart.sh
  • Permission errors
Test manually:
# From TTY
mango
mmsg cannot connect to Mango.Check:
echo $WAYLAND_DISPLAY  # Should show "wayland-0" or similar
echo $XDG_RUNTIME_DIR  # Should be /run/user/YOUR_UID
ls $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY  # Socket should exist
Fix:
# Ensure variables are set
export XDG_RUNTIME_DIR="/run/user/$(id -u)"
export WAYLAND_DISPLAY="wayland-0"

​
Configuration Issues

After editing ~/.config/mango/config.conf:
  1. Reload config: Press Super+R (if bound) or:
mmsg -s -d "reload_config"
  1. Verify syntax:
# Check for errors
grep -v "^#" ~/.config/mango/config.conf | grep -v "^$"
  1. Common syntax errors:
  • Extra spaces: bind=Alt, Return (wrong) vs bind=Alt,Return (correct)
  • Typos in command names
  • Invalid modifier keys
  1. Restart if needed:
mmsg -s -q  # Quit
mango       # Restart
Debug steps:
  1. Test key names:
# Install wev
yay -S wev  # or equivalent

# Run in Mango
wev
# Press keys to see their names
  1. Check modifier syntax:
Super = Windows key
Alt = Alt key
Ctrl = Control key
Shift = Shift key

# Multiple modifiers
Super+Shift  (correct)
SUPER+SHIFT  (wrong - case sensitive)
  1. Verify binding exists:
grep "^bind=" ~/.config/mango/config.conf
  1. Test with simple binding:
echo "bind=SUPER,t,spawn,foot" >> ~/.config/mango/config.conf
mmsg -s -d "reload_config"
Check script:
  1. Make executable:
chmod +x ~/.config/mango/autostart.sh
  1. Verify shebang:
head -1 ~/.config/mango/autostart.sh
# Should be: #!/bin/bash
  1. Test manually:
~/.config/mango/autostart.sh
  1. Check for errors:
# Add to top of autostart.sh
exec 2> ~/.config/mango/autostart.log
set -x

# Check log after starting Mango
cat ~/.config/mango/autostart.log
  1. Common issues:
  • Missing & for background processes
  • Commands exit with errors
  • Missing dependencies
Mango doesn’t have built-in window rules like Hyprland. Instead:
  1. Use custom script (see Custom Scripts):
cat > ~/.config/mango/scripts/window-rules.sh << 'EOF'
#!/bin/bash
mmsg -w -c | while read -r output type value; do
    if [ "$type" = "appid" ]; then
        case "$value" in
            firefox) mmsg -s -c 2 ;;
            spotify) mmsg -s -c 9 && mmsg -s -d "togglefloating" ;;
        esac
    fi
done
EOF

chmod +x ~/.config/mango/scripts/window-rules.sh
  1. Add to autostart.sh:
~/.config/mango/scripts/window-rules.sh &

​
Display Issues

Try these fixes:
  1. Disable animations:
echo "animations=0" >> ~/.config/mango/config.conf
mmsg -s -d "reload_config"
  1. Optimize blur:
# Reduce blur or disable
blur=0
# Or use optimized mode
blur_optimized=1
blur_params_num_passes=1
  1. Check GPU drivers:
# Check current driver
lspci -k | grep -A 3 -E "(VGA|3D)"

# For AMD, ensure AMDGPU is used
# For NVIDIA, use proprietary drivers
List outputs:
mmsg -O
Common issues:
  1. Monitor not detected:
# Check kernel sees it
ls /sys/class/drm/
dmesg | grep -i drm
  1. Wrong resolution: Mango auto-detects. If wrong:
# Use wlr-randr to check
wlr-randr

# Set mode manually (may need wlr-randr or similar tool)
  1. Monitor arrangement: Currently manual via mmsg:
# Focus specific output
mmsg -s -o "HDMI-A-1" -t 1

# Move window to output
mmsg -s -o "HDMI-A-1" -d "tagmon,left"
Set scale factor:Mango should auto-detect, but you can verify:
# Check current scale
mmsg -g -A
For specific applications:
# Qt apps
export QT_SCALE_FACTOR=2

# GTK apps (already handles wayland scaling)
# Should work automatically

# Electron apps
export ELECTRON_OZONE_PLATFORM_HINT=wayland
Add to autostart.sh or ~/.bashrc
Check XWayland:
# Verify XWayland is installed
which Xwayland

# Check if running
ps aux | grep Xwayland

# Check DISPLAY variable
echo $DISPLAY  # Should be something like :0
Enable XWayland in NixOS:
programs.xwayland.enable = true;
Test XWayland app:
xeyes  # Should show classic X11 eyes

​
Window Management Issues

Mango lacks built-in window rules. Use a script:
# See Custom Scripts guide
~/.config/mango/scripts/window-rules.sh
Alternatively, manually move after spawn:
# Move to tag 3
mmsg -s -c 3
Check sloppyfocus setting:
grep "sloppyfocus" ~/.config/mango/config.conf
Enable:
sloppyfocus=1  # Focus follows mouse
warpcursor=1   # Cursor warps to focused window
Disable:
sloppyfocus=0  # Click to focus
Mango determines floating on a per-window basis. To keep window floating:
# Toggle floating
mmsg -s -d "togglefloating"

# Check current state
mmsg -g -f
Bind to key:
bind=ALT,backslash,togglefloating,
Check gap settings:
grep "gap" ~/.config/mango/config.conf

# Should have:
gappih=5   # Horizontal inner
gappiv=5   # Vertical inner
gappoh=10  # Horizontal outer
gappov=10  # Vertical outer
smartgaps=0  # 0=always show gaps, 1=hide when single window
Toggle gaps:
# Keybind
bind=ALT+SHIFT,R,togglegaps

# Via mmsg
mmsg -s -d "togglegaps"

​
Input Issues

Set in config.conf:
xkb_rules_layout=us
# Or for multiple layouts:
xkb_rules_layout=us,ru
Check current layout:
mmsg -g -k
For multiple layouts, use setxkbmap:
# In autostart.sh
setxkbmap -layout "us,ru" -option "grp:alt_shift_toggle"
Configure trackpad in config.conf:
# Enable tap to click
tap_to_click=1

# Natural scrolling
trackpad_natural_scrolling=1

# Disable while typing
disable_while_typing=1

# Two-finger right click
tap_and_drag=1
Note: Requires re-login to apply.
Adjust in config.conf:
repeat_rate=25    # Characters per second
repeat_delay=600  # Milliseconds before repeat starts
Mango supports text-input-v2 and text-input-v3.For fcitx5:
# Install fcitx5 with wayland support
yay -S fcitx5-im fcitx5-chinese-addons

# Add to ~/.bashrc or ~/.profile
export GTK_IM_MODULE=fcitx
export QT_IM_MODULE=fcitx
export XMODIFIERS=@im=fcitx
export GLFW_IM_MODULE=ibus  # For some apps

# Start in autostart.sh
fcitx5 -d &

​
IPC / mmsg Issues

Debug mmsg:
# Verify connection
mmsg -T  # Should output tag count

# Check display
echo $WAYLAND_DISPLAY

# Test with verbose command
strace mmsg -g -t 2>&1 | grep -i "connect\|socket"
Common issues:
  • mmsg from different version than mango
  • Incorrect environment variables
  • Mango not running
This can happen if the compositor is busy or if there’s a pipe issue.Restart watch script:
pkill -f "mmsg -w"
~/.config/mango/scripts/your-watch-script.sh &
Make watch scripts resilient:
#!/bin/bash
while true; do
    mmsg -w -t | while read -r line; do
        # Process events
    done
    echo "mmsg disconnected, restarting..." >&2
    sleep 1
done

​
Performance Issues

Common causes:
  1. Animation/effects:
# Disable temporarily
animations=0
blur=0
shadows=0
  1. Too many watch scripts:
# Check running scripts
ps aux | grep mmsg
pkill -f "mmsg -w"  # Kill all watch processes
  1. Check compositor:
top  # Check mango CPU usage
Check:
ps aux | grep mango
# If memory grows over time, may be a leak
Report issue with:
# Memory info
cat /proc/$(pgrep mango)/status | grep -i mem

# Valgrind (for developers)
valgrind --leak-check=full mango

​
Reporting Issues

When reporting bugs, include:
  1. System info:
uname -a
lspci | grep VGA
mango --version
  1. Logs:
mango 2>&1 | tee ~/mango-error.log
  1. Configuration:
cat ~/.config/mango/config.conf
cat ~/.config/mango/autostart.sh
  1. Steps to reproduce
Submit to: GitHub Issues

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us