| name | troubleshoot |
| description | Diagnose and fix Gridix build, launch, and test failures. Use when builds fail, the app won't start, tests break, or dependencies are missing. |
| paths | ["Cargo.toml","Cargo.lock"] |
Troubleshooting
Build failures
Missing gtk3 headers
pkg-config: can't find gtk+-3.0
→ sudo apt-get install -y libgtk-3-dev (Ubuntu) / sudo pacman -S gtk3 (Arch) / sudo dnf install gtk3-devel (Fedora)
Missing xdo headers
pkg-config: can't find xdo
→ sudo apt-get install -y libxdo-dev (Ubuntu) / sudo pacman -S xdotool (Arch)
Rust not installed
→ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y && source "$HOME/.cargo/env"
App won't start
No X server (headless)
→ Use driver: source .claude/skills/run-gridix/driver.sh && launch
Or manually: Xvfb :99 -screen 0 1920x1080x24 &; export DISPLAY=:99; cargo run --release
Stale Xvfb lock
→ rm -f /tmp/.X99-lock /tmp/.X11-unix/X99 && pkill Xvfb
xdotool can't find window (Wayland)
→ export WINIT_UNIX_BACKEND=x11 before launching
Missing runtime libs
→ sudo apt-get install -y libgtk-3-0 xdotool imagemagick (Ubuntu)
Test failures
MySQL tests skip (expected)
MySQL integration tests are #[ignore]d. Need env vars:
GRIDIX_IT_MYSQL_HOST=127.0.0.1 GRIDIX_IT_MYSQL_PORT=3306 \
GRIDIX_IT_MYSQL_USER=root GRIDIX_IT_MYSQL_PASSWORD=secret \
GRIDIX_IT_MYSQL_DB=test \
cargo test --test mysql_cancel_integration -- --ignored --nocapture
input_router tests fail after keybinding changes
Check: did you change a key another test expects? Is the scope path correct? Is TextEntryGuard blocking the new shortcut?
Tooling missing
→ sudo apt-get install -y imagemagick (screenshots) / sudo pacman -S imagemagick
Config corruption
Backup then remove:
cp -r ~/.config/gridix ~/.config/gridix.bak
rm ~/.config/gridix/config.toml ~/.config/gridix/keymap.toml
Relaunch → fresh config created.
Keybindings in config.toml ignored
The keybindings field in config.toml is legacy read-only. Active keymap: ~/.config/gridix/keymap.toml. See /keybindings skill.
PostgreSQL/MySQL not detected
Check service installed + running. Ports: 5432 (PG), 3306 (MySQL). Use welcome page "Recheck" button or Ctrl+N to create connection manually.
