Troubleshooting

Common issues, solutions, and frequently asked questions for BobaMixer.

Quick Diagnostics

When encountering issues, always start with:

bash

boba doctor

This checks:

Configuration file syntax
File permissions
Database connectivity
API endpoint accessibility
Profile validity

Common Issues

Installation Issues

Command Not Found

Problem: bash: boba: command not found

Solutions:

Check if installed:
bash
```
which boba
```

If using Go install, add GOPATH to PATH:

bash

export PATH=$PATH:$(go env GOPATH)/bin
# Add to ~/.bashrc or ~/.zshrc for persistence

If using manual install, verify location:
bash
```
ls -l /usr/local/bin/boba
```
Make executable:
bash
```
sudo chmod +x /usr/local/bin/boba
```

Permission Denied

Problem: permission denied: /usr/local/bin/boba

Solutions:

bash

# Make executable
sudo chmod +x /usr/local/bin/boba

# Or reinstall with correct permissions
sudo mv boba /usr/local/bin/
sudo chmod +x /usr/local/bin/boba

macOS Security Warning

Problem: "boba cannot be opened because it is from an unidentified developer"

Solutions:

Open System Preferences → Security & Privacy
Click Allow Anyway next to the BobaMixer warning
Try running boba again

Or remove quarantine:

bash

xattr -d com.apple.quarantine /usr/local/bin/boba

Configuration Issues

Secrets File Permission Error

Problem: secrets.yaml must have 0600 permissions

Solution:

bash

chmod 600 ~/.boba/secrets.yaml

# Verify
ls -l ~/.boba/secrets.yaml
# Should show: -rw-------

YAML Syntax Error

Problem: error parsing config: yaml: line X: ...

Solutions:

Validate YAML syntax:
bash
```
yamllint ~/.boba/profiles.yaml
```
Common YAML mistakes:
- Incorrect indentation (use 2 spaces, not tabs)
- Missing quotes around special characters
- Invalid characters in keys or values

Example fixes:

yaml

# Wrong
headers:
  x-api-key: secret://anthropic_key

# Right
headers:
  x-api-key: "secret://anthropic_key"

Secret Not Found

Problem: secret not found: anthropic_key

Solutions:

Check secret exists:

bash

grep "anthropic_key" ~/.boba/secrets.yaml

Verify reference format:

yaml

# Correct
x-api-key: "secret://anthropic_key"

# Wrong
x-api-key: "secret://anthropic_key/"
x-api-key: "secret:anthropic_key"

Add missing secret:

bash

boba edit secrets
# Add: anthropic_key: sk-ant-your-key

Configuration Directory Not Found

Problem: config directory not found: ~/.boba

Solution:

bash

# Create directory
mkdir -p ~/.boba/logs
chmod 700 ~/.boba

# Generate default configs
boba doctor

Database Issues

Database Locked

Problem: database is locked

Solutions:

Find processes using database:
bash
```
lsof ~/.boba/usage.db
```
Kill if necessary:
bash
```
pkill -f boba
```

Remove stale locks:

bash

rm -f ~/.boba/usage.db-shm ~/.boba/usage.db-wal

Test:
bash
```
boba stats --today
```

Database Corruption

Problem: database disk image is malformed

Solutions:

Restore from backup:

bash

cp ~/.boba/usage.db.backup ~/.boba/usage.db

If no backup, try to recover:

bash

# Dump to SQL
sqlite3 ~/.boba/usage.db .dump > dump.sql

# Create new database
mv ~/.boba/usage.db ~/.boba/usage.db.corrupt
sqlite3 ~/.boba/usage.db < dump.sql

# Verify
sqlite3 ~/.boba/usage.db "PRAGMA integrity_check;"

If recovery fails, start fresh:

bash

mv ~/.boba/usage.db ~/.boba/usage.db.corrupt
boba doctor  # Creates new database

Slow Database Queries

Problem: Stats commands are slow

Solutions:

Vacuum database:
bash
```
sqlite3 ~/.boba/usage.db "VACUUM;"
```
Analyze:
bash
```
sqlite3 ~/.boba/usage.db "ANALYZE;"
```

Enable WAL mode:

bash

sqlite3 ~/.boba/usage.db "PRAGMA journal_mode=WAL;"

Increase cache:

bash

sqlite3 ~/.boba/usage.db "PRAGMA cache_size=-10000;"  # 10MB

API Issues

API Call Failed

Problem: API call failed: connection refused

Solutions:

Check internet connectivity:
bash
```
ping api.anthropic.com
```

Test endpoint manually:

bash

curl -v https://api.anthropic.com/v1/messages

Verify API key:

bash

# Check key exists
grep "anthropic_key" ~/.boba/secrets.yaml

# Test with curl
curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR-KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":10,"messages":[{"role":"user","content":"test"}]}'

Check firewall/proxy:

bash

# If behind proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

Invalid API Key

Problem: authentication failed: invalid API key

Solutions:

Verify key format:
- Anthropic: sk-ant-api03-...
- OpenAI: sk-proj-... or sk-...
- OpenRouter: sk-or-v1-...

Check for whitespace:

bash

# Should have no leading/trailing spaces
grep "anthropic_key" ~/.boba/secrets.yaml | cat -A

Test key directly:

bash

# Get key
KEY=$(grep "anthropic_key:" ~/.boba/secrets.yaml | cut -d: -f2 | tr -d ' ')

# Test
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":10,"messages":[{"role":"user","content":"test"}]}'

Regenerate key if needed

Rate Limited

Problem: rate limit exceeded

Solutions:

Wait before retrying
Check provider's rate limits
Use different profile:
bash
```
boba use alternate-profile
```
Contact provider to increase limits

Routing Issues

Rule Not Matching

Problem: Wrong profile selected

Solutions:

Test routing:
bash
```
boba route test "your text here"
```

Enable verbose mode:

bash

boba route test --verbose "your text here"

Check rule order (first match wins):

yaml

# Wrong order
rules:
  - if: "ctx_chars > 0"  # Matches everything!
    use: cheap
  - if: "ctx_chars > 50000"  # Never reached
    use: expensive

# Correct order
rules:
  - if: "ctx_chars > 50000"
    use: expensive
  - if: "ctx_chars > 0"
    use: cheap

Validate routing config:
bash
```
boba route validate
```

Regex Not Working

Problem: text.matches() not matching expected text

Solutions:

Test regex:

bash

# Python
python3 -c "import re; print(re.search(r'your.*pattern', 'your test text'))"

# Or use online tester: regex101.com

Common regex mistakes:

yaml

# Wrong: escaped pipe
if: "text.matches('format\\|prettier')"

# Right: pipe is OR operator
if: "text.matches('format|prettier')"

# Wrong: unescaped special characters
if: "text.matches('function()')"

# Right: escape parentheses
if: "text.matches('function\\(\\)')"

Use word boundaries:

yaml

# Wrong: matches "format" in "information"
if: "text.contains('format')"

# Right: matches whole word only
if: "text.matches('\\bformat\\b')"

Budget Issues

Budget Not Tracking

Problem: Budget status shows $0

Solutions:

Check database has data:

bash

sqlite3 ~/.boba/usage.db "SELECT COUNT(*) FROM usage_records;"

Verify cost calculations:
bash
```
boba stats --today
```
Check pricing config:
bash
```
boba edit pricing
```
View estimate accuracy:
bash
```
boba stats --by-estimate
```

Inaccurate Cost Estimates

Problem: Costs seem wrong

Solutions:

Check estimation level:
bash
```
boba stats --by-estimate
```
Add exact pricing:
bash
```
boba edit pricing
# Add model pricing
```
Verify profile costs:
bash
```
boba ls --profiles --verbose
```
Compare with provider bills

Alerts Not Showing

Problem: No budget alerts despite high spending

Solutions:

Check budget configured:
bash
```
boba budget --status
```

Verify alert thresholds:

bash

cat ~/.boba/profiles.yaml | grep -A 5 budget

Check action queue:
bash
```
boba action
```
View in TUI:
bash
```
boba
# Check notifications panel
```

TUI Issues

Garbled Display

Problem: TUI looks broken or garbled

Solutions:

Check terminal type:

bash

echo $TERM
# Should be xterm-256color or similar

Set terminal type:
bash
```
export TERM=xterm-256color
boba
```
Disable colors if needed:
bash
```
export NO_COLOR=1
boba
```
Try different terminal emulator

TUI Not Refreshing

Problem: Dashboard not updating

Solutions:

Check refresh rate:
bash
```
boba --refresh-rate 2  # 2 seconds
```
Restart TUI:
- Press q to quit
- Run boba again
Check for errors in logs:
bash
```
tail -f ~/.boba/logs/boba.log
```

Performance Issues

Slow Commands

Problem: All boba commands are slow

Solutions:

Check database size:
bash
```
du -h ~/.boba/usage.db
```
Vacuum database:
bash
```
sqlite3 ~/.boba/usage.db "VACUUM;"
```

Cleanup old data:

bash

sqlite3 ~/.boba/usage.db "DELETE FROM usage_records WHERE ts < strftime('%s', 'now', '-90 days');"
sqlite3 ~/.boba/usage.db "VACUUM;"

Optimize database:

bash

sqlite3 ~/.boba/usage.db "PRAGMA optimize;"
sqlite3 ~/.boba/usage.db "ANALYZE;"

High Memory Usage

Problem: BobaMixer using too much memory

Solutions:

Check memory:
bash
```
ps aux | grep boba
```
Reduce TUI refresh rate:
bash
```
boba --refresh-rate 10  # 10 seconds
```

Limit query size:

bash

# Instead of --30d, use shorter periods
boba stats --7d

Frequently Asked Questions

General

What is BobaMixer?

BobaMixer is a CLI tool for tracking, analyzing, and optimizing AI/LLM API usage and costs. It helps you understand spending patterns and make data-driven decisions about model selection.

Is BobaMixer free?

Yes! BobaMixer is open-source under the MIT license. You only pay for API usage from your providers.

Does BobaMixer intercept my API calls?

No. BobaMixer is a tracking tool. You explicitly invoke it when you want to track usage.

Installation

Which installation method should I use?

Homebrew: Easiest for macOS/Linux
Go install: Good if you have Go installed
Binary: Good for servers or without Go
Source: For development or custom builds

Can I install BobaMixer on Windows?

Yes, via WSL (Windows Subsystem for Linux). Native Windows support is planned.

Configuration

Where are configurations stored?

Default: ~/.boba/

Override with: export BOBA_HOME=/custom/path

Yes! Use symlinks for shared configs, keep individual secrets:

bash

ln -s /shared/boba/profiles.yaml ~/.boba/profiles.yaml
cp my-secrets.yaml ~/.boba/secrets.yaml
chmod 600 ~/.boba/secrets.yaml

How do I migrate from another tool?

Currently manual. Export data from other tool, import to BobaMixer database, or start fresh.

Usage

How accurate are cost estimates?

Exact (API response): 100%
Mapped (pricing config): 95-99%
Heuristic (character-based): 70-90%

Check with: boba stats --by-estimate

Can budgets block API calls?

No. BobaMixer uses "alert, don't interrupt" philosophy. You get warnings but work is never blocked.

How do I backup my data?

bash

# Backup database
sqlite3 ~/.boba/usage.db ".backup /path/to/backup.db"

# Backup configs
cp -r ~/.boba ~/.boba.backup