Troubleshooting

Solutions for common issues with Calliope desktop applications.

Installation Issues

macOS: “App is damaged and can’t be opened”

This happens because the app isn’t notarized.

Solution:

1. Right-click the app in Applications
2. Select Open
3. Click Open in the dialog
4. The app will now launch normally

Alternative:

xattr -cr /Applications/AILab.app
# or
xattr -cr /Applications/IDE.app

macOS: App won’t open on Apple Silicon

Make sure you downloaded the correct version:

• Apple Silicon (M1/M2/M3): Download ARM version
• Intel: Download Intel version

Windows: Installation blocked by SmartScreen

Solution:

1. Click More info
2. Click Run anyway
3. Installation proceeds

Windows: Missing DLL errors

Solution:

1. Install Visual C++ Redistributable
2. Download from Microsoft’s website
3. Restart computer

Linux: AppImage won’t run

Solution:

chmod +x Calliope-*.AppImage

sudo apt install fuse libfuse2

Linux: Missing dependencies

Ubuntu/Debian:

sudo apt install libgtk-3-0 libnotify4 libnss3 libxss1 libxtst6 xdg-utils

Fedora:

sudo dnf install gtk3 libnotify nss libXScrnSaver libXtst xdg-utils

Startup Issues

App crashes on launch

Try:

1. Delete settings folder:
   • macOS: ~/Library/Application Support/Calliope/
   • Windows: %APPDATA%/Calliope/
   • Linux: ~/.config/Calliope/
2. Relaunch app

Blank screen on startup

Solutions:

1. Disable GPU acceleration:
   • Launch from terminal with --disable-gpu
2. Update graphics drivers
3. Try different display scaling

Very slow to start

Possible causes:

• Large workspace history
• Many extensions
• Network issues checking for updates

Solutions:

1. Clear workspace history
2. Disable extensions temporarily
3. Check network settings

AI Features

AI not responding

Check:

1. API key is entered correctly
2. You have API credits remaining
3. Internet connection works
4. Provider service is up

For Ollama:

1. Ensure Ollama is running: ollama list
2. Verify model is pulled: ollama pull llama3
3. Check Ollama logs for errors

“Invalid API key” error

Solutions:

1. Regenerate API key from provider
2. Re-enter key in settings
3. Ensure no extra spaces in key
4. Check key hasn’t expired

AI responses are very slow

Solutions:

1. Try a faster model (gpt-4o-mini, claude-haiku)
2. Check network speed
3. For local models: ensure enough RAM/VRAM
4. Reduce context size in settings

AI gives wrong or outdated answers

Solutions:

1. Clear conversation history
2. Provide more context
3. Try different model
4. Update to latest app version

Performance Issues

High memory usage

Solutions:

1. Close unused files/tabs
2. Restart the app periodically
3. Disable memory-heavy extensions
4. Increase system RAM

For AI Lab:

%reset -f

High CPU usage

Possible causes:

• Background indexing
• Extension activity
• AI processing

Solutions:

1. Wait for indexing to complete
2. Disable unused extensions
3. Check for runaway processes in Activity Monitor/Task Manager

Slow file operations

Solutions:

1. Exclude large folders from watching:

   {
     "files.watcherExclude": {
       "**/node_modules/**": true,
       "**/.git/**": true
     }
   }
2. Store projects on SSD
3. Reduce number of open files

Network Issues

Can’t connect to AI provider

Check:

1. Internet connection works
2. Not blocked by firewall
3. VPN not interfering
4. Provider service status

Firewall rules (if needed):

• Allow outbound HTTPS (443)
• Allow api.openai.com
• Allow api.anthropic.com

Sync not working

Solutions:

1. Sign out and back in
2. Check Calliope account status
3. Verify network access to sync servers
4. Clear sync cache

Extension Issues

Extension won’t install

Solutions:

1. Check extension compatibility with app version
2. Try installing from command line
3. Check disk space
4. Clear extension cache

Extension causing crashes

Identify the culprit:

1. Launch with --disable-extensions
2. Enable extensions one by one
3. Identify which causes crash
4. Report to extension developer

Extensions not showing

Solutions:

1. Reload window (Cmd/Ctrl + R)
2. Check extension is enabled
3. Rebuild extensions:

   # AI Lab
   jupyter lab build
   
   # IDE
   ide --force-rebuild-extensions

Data Issues

Lost work / unsaved files

Recovery:

1. Check backup location:
   • macOS: ~/Library/Application Support/Calliope/Backups/
   • Windows: %APPDATA%/Calliope/Backups/
2. Look for .ipynb_checkpoints/ (notebooks)
3. Check Git history if using version control

Prevention:

1. Enable auto-save
2. Use Git for version control
3. Enable cloud sync

Database connection failed

Check:

1. Database server is running
2. Connection details are correct
3. Network allows connection
4. Credentials are valid

Test connection:

psql -h hostname -U username -d database

mysql -h hostname -u username -p

File encoding issues

Solutions:

1. Check file encoding in status bar
2. Try reopening with different encoding
3. Convert file:

   iconv -f ISO-8859-1 -t UTF-8 input.txt > output.txt

GPU Issues

GPU not detected

NVIDIA:

1. Install latest drivers
2. Install CUDA toolkit
3. Verify: nvidia-smi

For PyTorch:

import torch
print(torch.cuda.is_available())
print(torch.cuda.device_count())

Out of GPU memory

Solutions:

1. Reduce batch sizes
2. Use gradient checkpointing
3. Use smaller models
4. Enable memory efficient attention
5. Clear GPU cache:

   torch.cuda.empty_cache()

Getting Help

Before contacting support

Gather this information:

• App version (Help → About)
• Operating system and version
• Error messages (exact text)
• Steps to reproduce
• Relevant logs

Log locations

macOS:

~/Library/Logs/Calliope/

Windows:

%APPDATA%/Calliope/logs/

Linux:

~/.config/Calliope/logs/

Reporting bugs

1. Check existing issues on GitHub
2. Create new issue with:
   • Clear description
   • Steps to reproduce
   • Expected vs actual behavior
   • Logs and screenshots
   • System information