Skip to main content

Troubleshooting

Having trouble? Find your issue below and follow the steps to fix it.

Installation Issues​

macOS: "App can't be opened because it is from an unidentified developer"​

This is normal for apps downloaded from the internet (not the Mac App Store).

Fix:

  1. Open System Settings → Privacy & Security
  2. Scroll down to find the ClawDesk message
  3. Click "Open Anyway"

Alternative: Right-click the app → click Open → click Open again in the dialog.

macOS: "App is damaged and can't be opened"​

This usually means macOS quarantine is blocking the app.

Fix:

xattr -cr /Applications/ClawDesk.app

Then try opening ClawDesk again.

Linux: ".deb package fails to install"​

Fix: Install missing dependencies:

sudo apt install -f
sudo dpkg -i ClawDesk_amd64.deb

Windows: SmartScreen blocks the installer​

Fix: Click "More info" → "Run anyway"

Provider Issues​

"Invalid API key"​

Causes:

  • The API key was copied incorrectly (missing characters)
  • The key has expired or been revoked
  • You pasted the key with extra spaces

Fix:

  1. Go to your provider's website and copy the key again
  2. In ClawDesk, go to Settings → Providers
  3. Clear the old key and paste the new one carefully
  4. Make sure there are no spaces before or after the key
  5. Click Save

"No models available"​

Causes:

  • Provider not configured
  • API key not saved
  • For Ollama: no models pulled yet

Fix:

  1. Check Settings → Providers — is your provider set up?
  2. For Ollama: run ollama pull llama3.2 in your terminal
  3. For cloud providers: make sure you have API credits/billing set up

"Connection error" or "Network error"​

Fix:

  1. Check your internet connection
  2. For Ollama: make sure it's running — open terminal and run ollama serve
  3. Try a different provider to see if the issue is provider-specific
  4. Check if the provider is having an outage (visit their status page)

"Rate limit exceeded"​

Cause: You've sent too many requests to the AI provider in a short time.

Fix: Wait a minute and try again. ClawDesk's failover system will automatically try other models if available.

Chat Issues​

AI doesn't respond​

  1. Check that a provider is configured in Settings → Providers
  2. Check that a model is selected (click the model name at the top of chat)
  3. Check Logs page for error messages
  4. Try sending a simple "hello" message

Response comes very slowly​

Possible causes:

  • Slow internet connection (for cloud providers)
  • Large model on limited hardware (for local models)
  • Provider is overloaded

Fix:

  • Try a faster model (e.g., Haiku instead of Opus, Flash instead of Pro)
  • For local models: try a smaller model
  • Check your internet speed

Chat history disappeared​

Chat history is stored locally on your computer. It might disappear if:

  • You reinstalled ClawDesk and deleted the data directory
  • The database was corrupted

Fix: Check if the data directory exists at ~/.clawdesk/

Channel Issues​

Telegram bot doesn't respond​

  1. Make sure the channel shows green status in Channels page
  2. Check the bot token is correct (get a new one from @BotFather if unsure)
  3. Make sure you've started a chat with the bot (send /start)
  4. Check that a provider is configured (the bot needs an AI to respond with)

Discord bot isn't in my server​

  1. Go to the Discord Developer Portal
  2. Select your app → OAuth2 → URL Generator
  3. Check bot scope and the needed permissions
  4. Use the generated URL to invite the bot to your server

Bot responds but with errors​

Check the Logs page for detailed error messages. Common issues:

  • Provider API key expired
  • Model not available
  • Content filtered by provider

Local Model Issues​

Model won't start​

Possible causes:

  • Not enough free RAM
  • llama-server not found

Fix:

  1. Close other apps to free up memory
  2. Try a smaller model
  3. For built-in models: make sure llama-server is installed, or use Ollama instead

Ollama not detected​

Fix:

  1. Open your terminal and run: ollama serve
  2. Make sure it says "Listening on 127.0.0.1:11434"
  3. In ClawDesk: Settings → Providers → Ollama URL should be http://localhost:11434
  4. Click Save

Model runs out of memory​

Fix: Use a smaller model:

  • 8 GB RAM: Use 3B models or smaller
  • 16 GB RAM: Use 7-8B models
  • 32 GB RAM: Use up to 14B models

General Issues​

App won't start​

  1. Try restarting your computer
  2. Delete the config file and restart: rm ~/.clawdesk/config.toml (this resets settings)
  3. Check if another instance is already running

App crashes​

  1. Check Logs for error messages (~/.clawdesk/logs/)
  2. Try starting ClawDesk from the terminal to see error output
  3. File a GitHub issue with the error details

High memory usage​

  1. Stop local models you're not using (Local Models → Stop)
  2. Clear chat history if it's very long
  3. Restart ClawDesk

Getting More Help​

If your issue isn't listed here:

  1. Check the Logs — Click Logs in the sidebar for detailed error messages
  2. GitHub Issues — Search or create an issue at github.com/clawdesk/clawdesk/issues
  3. GitHub Discussions — Ask questions at github.com/clawdesk/clawdesk/discussions
  4. Discord — Join our community at discord.gg/clawdesk

When reporting a bug, include:

  • Your operating system (macOS, Linux, Windows) and version
  • ClawDesk version (check Settings or run clawdesk --version)
  • What you were doing when the problem happened
  • Any error messages from the Logs page