Troubleshooting

Solutions for common issues with Blueberry.

Installation Issues

”App is damaged” on macOS

macOS may block apps from unidentified developers.

Solution:

1. Right-click the Blueberry app
2. Select “Open”
3. Click “Open” in the dialog

Or in Terminal:

xattr -cr /Applications/Blueberry.app

App won’t launch

Check:

• macOS version is supported (requires macOS 12+)
• Apple Silicon Mac (Intel not currently supported)

Terminal Issues

Terminal not responding

Try:

1. Click the terminal panel to focus it
2. Press Ctrl+C to interrupt any running process
3. If still frozen, close the tab and open a new one

Commands not found

Your shell may not be loading profile files.

Solution: Add to your terminal startup command in Settings:

source ~/.zshrc

Session lost after sleep

Terminal sessions should persist for 30 minutes. If you’re losing them:

1. Check your network connection
2. Ensure Blueberry is still running (not suspended)
3. Try increasing the system sleep timeout

Editor Issues

Syntax highlighting not working

Check:

• File has correct extension (.ts, .tsx, .js, etc.)
• File isn’t too large (>2MB files may have limited highlighting)

LSP not providing completions

Check:

1. Language server is installed for that language
2. Project has a tsconfig.json (for TypeScript)
3. Try restarting Blueberry

Slow performance with large files

Files over 2MB may be slow. Consider:

• Splitting large files
• Disabling minimap in Settings

Preview Issues

Preview shows blank page

Check:

1. Dev server is running
2. URL is correct
3. No JavaScript errors (open DevTools with Cmd+Option+I)

localhost not loading

Try:

1. Verify your dev server is running
2. Check the port matches your server
3. Try 127.0.0.1 instead of localhost

CSS not updating

Try:

1. Hard refresh: Cmd+Shift+R
2. Clear browser cache in DevTools
3. Check for CSS compilation errors

Git Issues

Changes not showing

Check:

1. You’re in a git repository
2. Files are not in .gitignore
3. Try refreshing the Source Control panel

Commit failing

Check:

• Git is configured with name and email:

git config user.name "Your Name"
git config user.email "you@example.com"

Claude Integration Issues

”Not running in Blueberry terminal”

Claude must run in a Blueberry terminal to use MCP tools.

Solution:

1. Open a terminal tab in Blueberry
2. Run claude from that terminal

”Blueberry not running”

Check:

1. Blueberry is running
2. The project is open in Blueberry
3. You’re running Claude from within the project directory

Tools returning errors

Check:

1. Session token is set (happens automatically in Blueberry terminals)
2. Project is open and matches your working directory

Remote Access Issues

Can’t connect from other device

Check:

1. Both devices on same network
2. Remote access enabled in Blueberry settings
3. Firewall isn’t blocking the connection
4. Try IP address instead of hostname

Preview not working in remote mode

localhost URLs won’t work from other devices.

Solution: Start your dev server with --host:

npm run dev -- --host 0.0.0.0

Performance Issues

High CPU usage

Try:

1. Close unused terminal tabs
2. Close unused preview tabs
3. Disable minimap if not needed
4. Restart Blueberry

High memory usage

Check:

1. Number of open files (close unused tabs)
2. Preview tabs (close unused pages)
3. Terminal scrollback (clear with Cmd+K)

Getting Help

If you’re still stuck:

1. Check our FAQ
2. Join our Slack community 
3. Report issues on GitHub