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

bash
1# OS and architecture
2uname -a
3
4# Python version (must be 3.12.x, NOT 3.13)
5python3.12 --version 2>/dev/null || python3 --version
6
7# Check if venv exists
8ls -la .venv/bin/python 2>/dev/null && echo "Venv OK" || echo "PROBLEM: No .venv found"
9
10# Check venv Python version
11.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

bash
1# libmelee (critical — the Dolphin interface)
2.venv/bin/python -c "import melee; print('libmelee OK')" 2>&1
3
4# pyenet (libmelee dependency — C extension, common build failure)
5.venv/bin/python -c "import enet; print('pyenet OK')" 2>&1
6
7# nojohns CLI
8.venv/bin/python -m nojohns.cli list-fighters 2>&1
9
10# TensorFlow (only needed for Phillip)
11.venv/bin/python -c "import tensorflow as tf; print(f'TF {tf.__version__} OK')" 2>&1
12
13# slippi-ai (Phillip runtime)
14.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

bash
1# Config file exists
2cat ~/.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.

bash
1# Verify Dolphin path exists
2DOLPHIN_PATH=$(python3 -c "
3import tomllib
4with open('$HOME/.nojohns/config.toml', 'rb') as f:
5    c = tomllib.load(f)
6print(c.get('games', {}).get('melee', {}).get('dolphin_path', 'NOT SET'))
7" 2>/dev/null)
8echo "Dolphin path: $DOLPHIN_PATH"
9ls "$DOLPHIN_PATH" 2>/dev/null && echo "Path OK" || echo "PROBLEM: Path does not exist"
10
11# Verify ISO exists and check size
12ISO_PATH=$(python3 -c "
13import tomllib
14with open('$HOME/.nojohns/config.toml', 'rb') as f:
15    c = tomllib.load(f)
16print(c.get('games', {}).get('melee', {}).get('iso_path', 'NOT SET'))
17" 2>/dev/null)
18echo "ISO path: $ISO_PATH"
19ls -la "$ISO_PATH" 2>/dev/null || echo "PROBLEM: ISO file not found"

4. Dolphin Check

bash
1# macOS: Check Gatekeeper isn't blocking Dolphin
2# (only relevant on macOS)
3if [[ "$(uname)" == "Darwin" ]]; then
4    DOLPHIN_APP="$HOME/Library/Application Support/Slippi Launcher/netplay/Slippi Dolphin.app"
5    if [ -d "$DOLPHIN_APP" ]; then
6        echo "Dolphin app found"
7        xattr -l "$DOLPHIN_APP" 2>/dev/null | grep -q quarantine && \
8            echo "PROBLEM: Gatekeeper quarantine active. Fix: xattr -cr \"$DOLPHIN_APP\"" || \
9            echo "Gatekeeper OK"
10    else
11        echo "PROBLEM: Dolphin.app not found at expected location"
12        echo "Open Slippi Launcher and let it download Dolphin"
13    fi
14fi
15
16# Linux: Check Dolphin binary exists
17if [[ "$(uname)" == "Linux" ]]; then
18    NETPLAY_DIR="$HOME/.config/Slippi Launcher/netplay"
19    if [ -d "$NETPLAY_DIR" ]; then
20        echo "Slippi netplay dir found"
21        find "$NETPLAY_DIR" -name "dolphin-emu" -o -name "*.AppImage" 2>/dev/null
22    else
23        echo "PROBLEM: Slippi netplay directory not found"
24    fi
25fi

5. Phillip Check

bash
1# Model weights exist
2MODEL="fighters/phillip/models/all_d21_imitation_v3.pkl"
3if [ -f "$MODEL" ]; then
4    SIZE=$(wc -c < "$MODEL")
5    echo "Model weights: $SIZE bytes"
6    if [ "$SIZE" -lt 1000000 ]; then
7        echo "PROBLEM: Model file too small — may be corrupted"
8    else
9        echo "Model OK"
10    fi
11else
12    echo "PROBLEM: Model weights not found. Run: nojohns setup melee phillip"
13fi
14
15# slippi-ai installed
16if [ -d "fighters/phillip/slippi-ai" ]; then
17    echo "slippi-ai repo OK"
18else
19    echo "PROBLEM: slippi-ai not cloned. Run: nojohns setup melee phillip"
20fi

6. Network Check

bash
1# Arena reachable
2ARENA_URL=$(python3 -c "
3import tomllib
4with open('$HOME/.nojohns/config.toml', 'rb') as f:
5    c = tomllib.load(f)
6print(c.get('arena', {}).get('url', 'https://nojohns-arena-production.up.railway.app'))
7" 2>/dev/null || echo "https://nojohns-arena-production.up.railway.app")
8
9echo "Arena URL: $ARENA_URL"
10curl -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:

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."