Troubleshooting Common Issues

When something goes wrong in SpaceSpider, the fix is usually quick because there are only a few moving parts: the Tauri 2 app shell, the PTY layer (ConPTY on Windows, Unix PTY on macOS and Linux), the AI CLIs living inside the panes, and the license server. This page lists the most common issues, how to diagnose each one, and how to recover.

Where to look first

When a pane misbehaves, do this in order:

1. Look at the pane text. Most errors print a readable message.
2. Try the same command outside SpaceSpider (claude --version, codex, etc.) to isolate whether the issue is the CLI or the app.
3. Restart the pane with Ctrl+Shift+R (Cmd+Shift+R on macOS).
4. Check the app log file (paths below).
5. Restart SpaceSpider.

Most issues are resolved by steps 1-3.

App log locations

• Windows: %APPDATA%\SpaceSpider\logs\
• macOS: ~/Library/Logs/SpaceSpider/
• Linux: ~/.config/SpaceSpider/logs/

Logs rotate daily. The current log is named spacespider-YYYY-MM-DD.log.

Pane fails to spawn

"Command not found"

The CLI is not on your PATH in the environment SpaceSpider inherited.

1. Open a regular terminal and run the CLI name. If it fails there too, install the CLI.
2. If it works in the terminal but not in SpaceSpider, SpaceSpider was launched before the PATH change took effect. Close and reopen SpaceSpider from a fresh terminal.

Pane exits immediately with no banner

The CLI spawned and crashed in the first millisecond. Likely causes:

• Missing auth token or API key.
• The CLI detected a headless session and refused.
• A DLL or shared library is missing.

Run the same command in a regular terminal for the real error message.

Pane shows "Access denied" on spawn

On Windows, this is typically Windows Defender or an Enterprise EDR blocking the PTY. Add an exclusion for the SpaceSpider install directory.

Rendering and font issues

Box-drawing characters render as squares

Your terminal font does not include box glyphs. Install a Nerd Font (Fira Code Nerd Font, JetBrains Mono Nerd Font) and pick it in Settings > Terminal > Font.

Colors look muted

xterm.js defaults to 256 colors. Enable truecolor in Settings > Terminal > True color.

Output occasionally shows replacement characters

PTY output is decoded from UTF-8 in chunks. A multibyte character that straddles a chunk boundary can render as U+FFFD. This is rare and only affects non-ASCII output. A fix that buffers across boundaries is on the roadmap.

HiDPI looks blurry

Windows Scaling above 150 percent on some displays renders WebView text soft. Try 125 or 150 percent, and relaunch.

Input issues

Arrow keys insert letters

On Windows 10 below build 19045, ConPTY has a known input bug. Update Windows to 22H2.

Backspace is broken

Terminal compatibility setting in your shell profile. Set TERM=xterm-256color in your shell or in SpaceSpider's terminal settings.

Paste pastes only partial content

Large pastes trigger bracketed paste mode. If the CLI inside the pane does not support it, disable bracketed paste in Settings > Terminal.

AI CLI-specific issues

Claude Code: "Please run claude login"

Run claude login in a regular terminal once to seed the credential file, then restart the pane.

Codex: "Authentication required"

Run codex login once in a regular terminal, or export OPENAI_API_KEY before launching SpaceSpider.

Qwen Code: "Model not found"

The provider does not expose that exact model name. Run qwen-code models list in a shell pane to see available names, and pin one via QWEN_CODE_MODEL.

Kimi: "API key missing"

Set MOONSHOT_API_KEY (or OPENROUTER_API_KEY if routing) before launching SpaceSpider. Env vars exported after launch are not picked up by existing panes.

Deeper guidance per CLI lives on Claude Code, Codex, Qwen Code, and Kimi CLI.

Performance issues

High CPU with many panes idle

The xterm.js renderer can stay active if a CLI emits a constant stream of spinner characters. Disable the spinner in the CLI, or use its quiet mode.

Memory climbs over hours

Each pane's scrollback defaults to 10,000 lines. If a pane has been emitting verbose logs for a long time, clear it with Ctrl+L or restart the pane with Ctrl+Shift+R.

Grid feels sluggish on an older laptop

Drop from 4 panes to 2, or turn off the accessibility focus ring if enabled.

Auto-update issues

"Signature verification failed"

Corrupt download. Retry the update check. If it keeps failing, download the installer manually. See Updating SpaceSpider.

Update banner never appears

Automatic checks may be disabled. Open Settings > Updates and click Check for updates now.

Cannot apply update on Linux AppImage

Some sandbox configurations block self-overwrite. Replace the AppImage file manually.

License issues

"Seat limit reached"

You are at the cap. Deactivate an existing machine from inside SpaceSpider or via the web dashboard. See Licensing.

"License server unreachable"

Network or firewall blocks. Use offline activation (Settings > License > Activate offline).

Trial expired after reinstall

Reinstalling can wipe the app data directory on some platforms. Re-activate with your key; your seat count is not consumed twice for the same machine.

Space creation issues

Folder picker opens to the wrong directory

Your OS file chooser remembers the last location. Navigate up and pick again.

"Space already exists"

A space with the same name at the same path already exists. Rename or pick another directory.

Space card shows a broken icon

The icon could not be loaded. Rename the space; SpaceSpider regenerates the icon from the new name.

Windows-specific issues

SmartScreen blocks the installer

Click More info then Run anyway. The MSI is signed.

Defender quarantines DLLs during development

If you are building from source, redirect the Rust target directory away from %USERPROFILE%\Documents. SpaceSpider's own build does this via .cargo/config.toml pointing to %LOCALAPPDATA%\spacespider-target.

macOS-specific issues

"App is damaged and can't be opened"

macOS misapplied quarantine. Run:

xattr -dr com.apple.quarantine /Applications/SpaceSpider.app

Files and Folders permission never prompts

macOS hides the prompt after dismiss. Approve manually in System Settings > Privacy & Security > Files and Folders.

Linux-specific issues

AppImage complains about fuse

Install libfuse2 on Ubuntu, or run with --appimage-extract-and-run.

Blank window on launch

WebKitGTK 4.1 missing or broken. Reinstall:

sudo apt install --reinstall libwebkit2gtk-4.1-0

Cursor artifacts on Wayland

Force X11 backend:

GDK_BACKEND=x11 spacespider

Collect diagnostics for a bug report

When asking for help, include:

1. SpaceSpider version (visible in Settings > About).
2. OS and version (winver, sw_vers, or uname -a).
3. The relevant log file from the locations above.
4. The exact command you assigned to the pane and its version (claude --version, etc.).
5. A short description of what you expected and what happened.

Attach the log with any sensitive paths redacted. SpaceSpider does not send logs automatically.

Frequently asked questions

My spaces disappeared after an update

Check the app data directory for spaces.json. If it is missing, restore from your OS backup. SpaceSpider does not delete spaces.json on update.

Can I reset SpaceSpider to a clean state?

Quit the app and delete the app data directory:

• Windows: %APPDATA%\SpaceSpider
• macOS: ~/Library/Application Support/SpaceSpider
• Linux: ~/.config/SpaceSpider

Relaunching recreates a fresh directory.

Does SpaceSpider need root or admin?

No. Per-user install and per-user data directory.

Where do I report a bug?

The issue tracker linked from the app's Settings > About > Report an issue. Include the diagnostics listed above.

Is there a way to pin a previous version?

Yes. Download an older installer from the releases archive and disable auto-update in Settings > Updates.

Related reading

• Updating SpaceSpider
• License Activation, Seats, and Transfers
• Getting Started with SpaceSpider