< Back to README

Run the --doctor flag to check your system for common issues:

# Deb install
claude-desktop --doctor

# AppImage
./claude-desktop-*.AppImage --doctor

This runs 10 checks and prints pass/fail results with suggested fixes:

Example output:

Claude Desktop Diagnostics
================================

[PASS] Installed version: 1.1.4498-1.3.15
[PASS] Display server: Wayland (WAYLAND_DISPLAY=wayland-0)
[PASS] Electron: found at /usr/lib/claude-desktop/node_modules/electron/dist/electron
[PASS] Chrome sandbox: permissions OK
[PASS] SingletonLock: no lock file (OK)
[PASS] MCP config: valid JSON
[PASS] Node.js: v22.14.0
[PASS] Desktop entry: /usr/share/applications/claude-desktop.desktop
[PASS] Disk space: 632284MB free
[PASS] Log file: 1352KB

All checks passed.

When opening an issue, include the output of --doctor to help with diagnosis.

Runtime logs are available at:

~/.cache/claude-desktop-debian/launcher.log

If the window doesn't scale correctly on first launch:

1. Right-click the Claude Desktop tray icon
2. Select "Quit" (do not force quit)
3. Restart the application

This allows the application to save display settings properly.

If the global hotkey (Ctrl+Alt+Space) doesn't work, ensure you're not running in native Wayland mode:

1. Check your logs at ~/.cache/claude-desktop-debian/launcher.log
2. Look for "Using X11 backend via XWayland" - this means hotkeys should work
3. If you see "Using native Wayland backend", unset CLAUDE_USE_WAYLAND or ensure it's not set to 1

Note: Native Wayland mode doesn't support global hotkeys due to Electron/Chromium limitations with XDG GlobalShortcuts Portal.

See CONFIGURATION.md for more details on the CLAUDE_USE_WAYLAND environment variable.

AppImages run with --no-sandbox due to electron's chrome-sandbox requiring root privileges for unprivileged namespace creation. This is a known limitation of AppImage format with Electron applications.

For enhanced security, consider:

• Using the .deb package instead
• Running the AppImage within a separate sandbox (e.g., bubblewrap)
• Using Gear Lever's integrated AppImage management for better isolation

If you encounter recurring "API Error: 401" messages after periods of inactivity, the cached OAuth token may need to be cleared. This is an upstream application issue reported in #156.

To fix manually (credit: MrEdwards007):

1. Close Claude Desktop completely
2. Edit ~/.config/Claude/config.json
3. Remove the line containing "oauth:tokenCache" (and any trailing comma if needed)
4. Save the file and restart Claude Desktop
5. Log in again when prompted

A scripted solution is also available at the bottom of this comment.

# Remove package
sudo apt remove claude-desktop

# Remove the repository and GPG key
sudo rm /etc/apt/sources.list.d/claude-desktop.list
sudo rm /usr/share/keyrings/claude-desktop.gpg

# Remove package
sudo dnf remove claude-desktop

# Remove the repository
sudo rm /etc/yum.repos.d/claude-desktop.repo

# Using yay
yay -R claude-desktop-appimage

# Or using paru
paru -R claude-desktop-appimage

# Or using pacman directly
sudo pacman -R claude-desktop-appimage

# Remove package
sudo apt remove claude-desktop
# Or: sudo dpkg -r claude-desktop

# Remove package and configuration
sudo dpkg -P claude-desktop

# Remove package
sudo dnf remove claude-desktop
# Or: sudo rpm -e claude-desktop

1. Delete the .AppImage file
2. Remove the .desktop file from ~/.local/share/applications/
3. If using Gear Lever, use its uninstall option

rm -rf ~/.config/Claude