Skip to main content

​
Viewing logs

The first step when debugging any issue is to check the logs: 
bolly logs
This streams logs in real time. Press Ctrl+C to stop. For Docker installations, use docker logs bolly -f instead.
If you installed Bolly to a custom directory, set BOLLY_HOME before running CLI commands.

​
Installation issues

Install curl through your package manager:
# Ubuntu/Debian
sudo apt install curl

# macOS (should be pre-installed)
brew install curl

# Fedora
sudo dnf install curl
The install script may need sudo for placing the binary in /usr/local/bin:
curl -fsSL https://bollyai.dev/install.sh | sudo bash
Or run with a custom install location:
curl -fsSL https://bollyai.dev/install.sh | INSTALL_DIR=~/.local/bin bash
The binary might not be in your PATH. Add it:
# If installed to ~/.local/bin
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Or for zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
This happens with unsigned binaries. To allow it:
  1. Go to System Settings > Privacy & Security
  2. Scroll down to the Security section
  3. Click Open Anyway next to the Bolly warning
Or use the terminal:
xattr -d com.apple.quarantine /usr/local/bin/bolly
Check the service logs:
journalctl -u bolly -n 50 --no-pager
Common causes:
  • Port in use: Another service is using port 26559 — change the port or stop the conflicting service
  • Permission issues: The service user needs read/write access to ~/.bolly/

​
Docker issues

Check the logs:
docker logs bolly
Usually caused by:
  • Port conflict (another container using 26559)
  • Volume permission issues
Verify the container is running:
docker ps | grep bolly
If running, check port mapping:
docker port bolly
If not running, check why it stopped:
docker logs bolly --tail 50
Ensure you’re using a named volume or bind mount:
# Named volume (recommended)
docker run -v bolly-data:/data ...

# Bind mount
docker run -v ~/.bolly:/data ...
Without -v, data is lost when the container is removed.

​
Desktop app issues

Try these steps in order:
  1. Clear quarantine flag: xattr -cr /Applications/Bolly.app
  2. Check system requirements: macOS 12+ required
  3. Reinstall: Delete from Applications and download the latest release
Computer use requires accessibility permissions:
  • macOS: Go to System Settings > Privacy & Security > Accessibility and enable Bolly
  • Linux: Ensure Bolly has access to X11/Wayland display server
  • Windows: Run as administrator if screen capture fails
  1. Click More info on the SmartScreen dialog
  2. Click Run anyway
This warning appears because the binary isn’t signed with a Windows code signing certificate.

​
API key issues

Check the following:
  • Anthropic keys start with sk-ant-
  • Verify the key is active in your Anthropic dashboard
  • Try re-entering the key through Bolly’s settings in the web interface
  • Check your Anthropic billing to ensure you have credits
  • Anthropic enforces rate limits based on your plan tier
  • If hitting rate limits frequently, consider upgrading your Anthropic plan
  • Ensure the key was generated at aistudio.google.com, not the regular Google Cloud Console
  • The key should start with AIzaSy
  • Check that the Generative Language API is enabled in your Google Cloud project

​
Runtime issues

Possible causes:
  • Network latency: Bolly calls the Anthropic API for every response. Slow internet = slow responses.
  • Long conversation context: Very long chats use more tokens and take longer to process. Start a new chat periodically.
  • Tool-heavy interactions: Tool calls add extra API round-trips. This is normal.
  • Without Google AI key: Search uses BM25 (keyword-based) — try using more specific keywords
  • With Google AI key: Vector search provides better semantic matching. Add the key if you haven’t.
  • New instance: Memory builds over time. The more you talk to Bolly, the better its recall.
Check that:
  • Bolly is running (not stopped/paused)
  • The heartbeat.md file exists in the instance directory
  • There are no errors in the logs during heartbeat cycles
# Check logs for heartbeat activity
journalctl -u bolly | grep -i heartbeat
If your companion stops responding to messages, try restarting the instance — this often resolves the issue.
Find what’s using the port:
lsof -i :26559
Either stop the conflicting service or run Bolly on a different port:
PORT=3000 bolly

​
Build issues (from source)

  • Ensure you have the latest stable Rust: rustup update stable
  • Clean and rebuild: cargo clean && cargo build --release
  • Check for missing system dependencies (OpenSSL, pkg-config)
# Ubuntu/Debian
sudo apt install build-essential pkg-config libssl-dev

# macOS
brew install openssl pkg-config
  • Ensure you’re using pnpm, not npm or yarn
  • Install pnpm if missing: npm install -g pnpm
  • Clear cache: pnpm store prune
  • Delete node_modules and retry: rm -rf node_modules && pnpm install
Follow the Tauri 2 prerequisites for your platform. Common missing dependencies:
# Ubuntu/Debian
sudo apt install libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev

# Fedora
sudo dnf install webkit2gtk4.1-devel libappindicator-gtk3-devel librsvg2-devel

​
Getting help

If your issue isn’t covered here:

GitHub Issues

Search existing issues or file a new one with logs and reproduction steps.

Discord Community

Ask the community for help — someone has probably encountered the same issue.
When reporting issues, include:
  • Your operating system and version
  • Installation method used
  • Relevant log output
  • Steps to reproduce the problem