Is the server actually running? Open the 🤖 panel — it should say Server: ON with a URL. If not, click ON.
Did the dev app fully start? Look in PowerShell for MCP server listening on http://127.0.0.1:47821/mcp. If only the GUI is up but no listener was started, the MCP server is off.
Did you toggle the per-pane 🤖 chip? Even with the server running, panes are default-deny. Claude sees zero panes until you flip the chip on the ones you want exposed.
Bearer token mismatch? If you regenerated the token in the panel after setting up Claude Desktop, restart the extension (close Claude Desktop, reopen). The .mcpb wrapper reads the token fresh at launch, but Claude has to actually relaunch the extension subprocess.
Wrong port? The default is 47821 but falls back to OS-picked if taken. Check the panel for the actual port; it's also in %APPDATA%\com.megaproxy.tiletopia\mcp.json.

Claude Desktop says "extension failed to start" or "tiletopia.mcpb invalid"

Node 18+ required. The wrapper inside the bundle uses npx. Open PowerShell, run node --version — should be ≥ 18. Install Node from nodejs.org if missing.
npx not on PATH. Same fix — installing Node puts npx next to it.
Wrong tiletopia install location. The wrapper expects %APPDATA%\com.megaproxy.tiletopia\mcp.json. If you've installed tiletopia somewhere unusual or never run it once, that file won't exist. Run tiletopia once and start the MCP server to create the file.

Idle indicator never clears / always shows red

If a pane stays red even after typing in it: that's a bug, file an issue. If a pane goes red after 5 s of silence even though something is "running": that's the intended behavior — tiletopia v0.2.x has no notion of "the user is reading output, don't flag idle". A claude-foreground filter was attempted and reverted; see memory.md for the gory details.

"WSL says firewall is blocking port 47821"

Windows Defender Firewall auto-creates Block rules for new executables hitting the network on the Public profile. Block beats Allow.

# Wipe any auto-created tiletopia rules (run as admin)
Get-NetFirewallApplicationFilter | Where-Object Program -Like "*tiletopia*" |
  Get-NetFirewallRule | Remove-NetFirewallRule

# Allow the MCP port through, all profiles
New-NetFirewallRule -DisplayName "tiletopia MCP" -Direction Inbound `
  -Action Allow -Protocol TCP -LocalPort 47821 -Profile Any

(Replace 47821 with your actual port if you've customized it.)

WSL connectivity

Claude running inside WSL can't reach `127.0.0.1:47821`

WSL2 in default NAT mode does not share Windows's 127.0.0.1. Two options:

Option A: Use the WSL gateway IP.

Inside WSL:

ip route show default | awk '{print $3}'

Use that IP (typically 172.x.x.1) instead of 127.0.0.1 in your .mcp.json URL. Caveat: the gateway IP changes after every WSL restart.

Option B: Enable WSL2 mirrored networking. Win 11 22H2+ only. Edit %UserProfile%\.wslconfig:

[wsl2]
networkingMode=mirrored

Then in PowerShell:

wsl --shutdown

After WSL restarts, 127.0.0.1 inside WSL transparently reaches Windows listeners. This is the better long-term answer if you're on a recent Windows build.

Saved SSH passwords

"Saved password" doesn't auto-type at the SSH prompt

The autotype window is 30 seconds from spawn. If the SSH handshake is slow (cold connection, network) and the prompt arrives later, the autotyper has already disarmed.
The matcher looks for password: (case-insensitive) or passphrase in the recent output. Some custom SSH banners suppress the standard prompt — those won't trigger.
Check the saved status: in the Manage hosts dialog, the 🔒 icon indicates a stored password. If absent, save one.

"Saved passwords missing after Windows reboot"

The credential store uses DPAPI tied to your Windows account. Things that wipe it:

Logging in as a different Windows user
Domain account password reset by IT (sometimes invalidates DPAPI)
Migrating to a new machine without exporting credentials

Saved passwords are convenience, not a sync mechanism. Source-of-truth lives in hosts.json for everything except the password itself.

Build from source

`pnpm install` hangs or crashes with `isDriveExFat`

You're running pnpm against a \\wsl.localhost\... UNC path. pnpm 11.x crashes inside isDriveExFat on those.

Fix: clone to a Windows-native drive (e.g. D:\dev\tiletopia\). If you want a WSL-side symlink for editing convenience, that's fine — just make sure your PowerShell cwd when running pnpm is the Windows path:

cd D:\dev\tiletopia
pnpm install     # works
pnpm tauri dev   # works

The Rust toolchain (cargo) lives on the Windows host too; cargo from inside WSL will error on the Windows-targeting deps.

`cargo test --lib` panics with `policy_with` field error

Outdated checkout — the policy_with test helper was missing the ssh_safeguards field for a couple of days before PR-4 fixed it. Pull main.

Tauri / Windows

Dev window opens with broken layout / blank panes

Hard-refresh the WebView2:

Right-click anywhere → Inspect element → Console, type location.reload().
Or close the window and pnpm tauri dev again.

If it persists, check the console for an error from React / xterm.js and file an issue with the error text.

SmartScreen blocks the installer on launch

Expected — installer isn't code-signed. Click More info → Run anyway. SmartScreen learns and stops asking after the first install.

Still stuck?

Open an issue with: tiletopia version (Help → About or the title bar), Windows build (winver), WSL version (wsl --version), exact error text or screenshot, and steps to reproduce. The shorter and more reproducible the report, the faster it gets fixed.

Troubleshooting

MCP

Claude can't reach tiletopia — 401 Unauthorized or connection refused