---

name: troubleshoot description: Diagnose No Johns setup issues. Checks Python, Dolphin, ISO, arena connectivity, and common problems.

Setup Troubleshooter

Diagnose and fix common No Johns setup problems. Run each check in order and report findings at the end.

Steps

1. System Check

# OS and architecture
uname -a

# Python version (must be 3.12.x, NOT 3.13)
python3.12 --version 2>/dev/null || python3 --version

# Check if venv exists
ls -la .venv/bin/python 2>/dev/null && echo "Venv OK" || echo "PROBLEM: No .venv found"

# Check venv Python version
.venv/bin/python --version 2>/dev/null

Expected: Python 3.12.x. If 3.13, pyenet won't build. If no venv, user needs python3.12 -m venv .venv.

2. Package Check

# libmelee (critical — the Dolphin interface)
.venv/bin/python -c "import melee; print('libmelee OK')" 2>&1

# pyenet (libmelee dependency — C extension, common build failure)
.venv/bin/python -c "import enet; print('pyenet OK')" 2>&1

# nojohns CLI
.venv/bin/python -m nojohns.cli list-fighters 2>&1

# TensorFlow (only needed for Phillip)
.venv/bin/python -c "import tensorflow as tf; print(f'TF {tf.__version__} OK')" 2>&1

# slippi-ai (Phillip runtime)
.venv/bin/python -c "import slippi_ai; print('slippi-ai OK')" 2>&1

Common failures:

• import enet fails → pyenet build issue. See docs/TROUBLESHOOTING.md "pyenet Build Failure"
  • macOS fix: LDFLAGS="-L/opt/homebrew/lib -lenet" CFLAGS="-I/opt/homebrew/include" .venv/bin/pip install --no-cache-dir --no-binary :all: pyenet
  • Linux fix: sudo apt install -y libenet-dev && .venv/bin/pip install --force-reinstall pyenet
• import melee fails → libmelee not installed. Run .venv/bin/pip install -e .
• import tensorflow fails with mutex lock → TF 2.20 on macOS ARM. Fix: .venv/bin/pip install "tensorflow==2.18.1" "tf-keras==2.18.0"

3. Config Check

# Config file exists
cat ~/.nojohns/config.toml 2>/dev/null || echo "PROBLEM: No config.toml — run 'nojohns setup melee'"

Verify these fields in ~/.nojohns/config.toml:

• dolphin_path: Must exist and contain "netplay" in the path string (libmelee validates this)
  • macOS: ~/Library/Application Support/Slippi Launcher/netplay
  • Linux: ~/.config/Slippi Launcher/netplay
• iso_path: Must exist and be >500MB (a real Melee ISO is ~1.3GB)
• connect_code: Format XXXX#NNN (4 letters, hash, 1-3 digits). Avoid codes with '9' on macOS Sequoia.

# Verify Dolphin path exists
DOLPHIN_PATH=$(python3 -c "
import tomllib
with open('$HOME/.nojohns/config.toml', 'rb') as f:
    c = tomllib.load(f)
print(c.get('games', {}).get('melee', {}).get('dolphin_path', 'NOT SET'))
" 2>/dev/null)
echo "Dolphin path: $DOLPHIN_PATH"
ls "$DOLPHIN_PATH" 2>/dev/null && echo "Path OK" || echo "PROBLEM: Path does not exist"

# Verify ISO exists and check size
ISO_PATH=$(python3 -c "
import tomllib
with open('$HOME/.nojohns/config.toml', 'rb') as f:
    c = tomllib.load(f)
print(c.get('games', {}).get('melee', {}).get('iso_path', 'NOT SET'))
" 2>/dev/null)
echo "ISO path: $ISO_PATH"
ls -la "$ISO_PATH" 2>/dev/null || echo "PROBLEM: ISO file not found"

4. Dolphin Check

# macOS: Check Gatekeeper isn't blocking Dolphin
# (only relevant on macOS)
if [[ "$(uname)" == "Darwin" ]]; then
    DOLPHIN_APP="$HOME/Library/Application Support/Slippi Launcher/netplay/Slippi Dolphin.app"
    if [ -d "$DOLPHIN_APP" ]; then
        echo "Dolphin app found"
        xattr -l "$DOLPHIN_APP" 2>/dev/null | grep -q quarantine && \
            echo "PROBLEM: Gatekeeper quarantine active. Fix: xattr -cr \"$DOLPHIN_APP\"" || \
            echo "Gatekeeper OK"
    else
        echo "PROBLEM: Dolphin.app not found at expected location"
        echo "Open Slippi Launcher and let it download Dolphin"
    fi
fi

# Linux: Check Dolphin binary exists
if [[ "$(uname)" == "Linux" ]]; then
    NETPLAY_DIR="$HOME/.config/Slippi Launcher/netplay"
    if [ -d "$NETPLAY_DIR" ]; then
        echo "Slippi netplay dir found"
        find "$NETPLAY_DIR" -name "dolphin-emu" -o -name "*.AppImage" 2>/dev/null
    else
        echo "PROBLEM: Slippi netplay directory not found"
    fi
fi

5. Phillip Check

# Model weights exist
MODEL="fighters/phillip/models/all_d21_imitation_v3.pkl"
if [ -f "$MODEL" ]; then
    SIZE=$(wc -c < "$MODEL")
    echo "Model weights: $SIZE bytes"
    if [ "$SIZE" -lt 1000000 ]; then
        echo "PROBLEM: Model file too small — may be corrupted"
    else
        echo "Model OK"
    fi
else
    echo "PROBLEM: Model weights not found. Run: nojohns setup melee phillip"
fi

# slippi-ai installed
if [ -d "fighters/phillip/slippi-ai" ]; then
    echo "slippi-ai repo OK"
else
    echo "PROBLEM: slippi-ai not cloned. Run: nojohns setup melee phillip"
fi

6. Network Check

# Arena reachable
ARENA_URL=$(python3 -c "
import tomllib
with open('$HOME/.nojohns/config.toml', 'rb') as f:
    c = tomllib.load(f)
print(c.get('arena', {}).get('url', 'https://nojohns-arena-production.up.railway.app'))
" 2>/dev/null || echo "https://nojohns-arena-production.up.railway.app")

echo "Arena URL: $ARENA_URL"
curl -s --max-time 5 "$ARENA_URL/health" 2>/dev/null || echo "PROBLEM: Arena unreachable"

7. Known Issues Reference

If the checks above pass but things still don't work, check these known issues in docs/TROUBLESHOOTING.md:

| Symptom | Issue | Fix | |---------|-------|-----| | Connect codes with '9' fail on Sequoia | Position 3 bug | Use a code without '9' | | Netplay freezes at stock loss | Rollback desync | Set online_delay=6 | | Phillip doesn't move in netplay | Missing on_game_start | Update to latest code | | mutex lock failed on TF import | TF 2.20 bug on ARM | Install TF 2.18.1 | | Unknown path from libmelee | Path missing "netplay" | Use Slippi Launcher's netplay dir | | Menu stuck on 2nd+ match | libmelee state leak | Use subprocess per match | | CSS stuck at character select | Intermittent | Kill and restart matchmake |

8. Report

After running all checks, print a summary:

=== No Johns Setup Diagnostic ===
System:     [OS, arch, Python version]
Packages:   [OK / PROBLEMS: list]
Config:     [OK / PROBLEMS: list]
Dolphin:    [OK / PROBLEMS: list]
Phillip:    [OK / PROBLEMS: list]
Network:    [OK / PROBLEMS: list]

[For each PROBLEM, include the specific fix command]

If everything passes: "Setup looks good. Try nojohns fight random do-nothing for a smoke test."