Common Issues

This guide covers the most frequently encountered issues when using Gonzo and their solutions. For AI-specific or format-specific issues, see the dedicated troubleshooting pages.

Installation Problems

Command Not Found After Installation

Symptom: Running gonzo returns "command not found" error.

Causes & Solutions:

Go installation - PATH not configured

# Check if GOPATH/bin is in PATH
echo $PATH | grep -q "$(go env GOPATH)/bin" && echo "Found" || echo "Missing"

# Fix: Add to your shell profile
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc

# Or for zsh
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.zshrc
source ~/.zshrc

Binary installation - not in PATH

# Move to standard location
sudo mv gonzo /usr/local/bin/

# Or add current directory to PATH
export PATH=$PATH:$(pwd)

Verify installation
```
which gonzo
gonzo --version
```

Permission Denied When Running Binary

Symptom: permission denied when trying to execute gonzo.

Solution:

# Make executable
chmod +x gonzo

# If in system directory
sudo chmod +x /usr/local/bin/gonzo

# Verify permissions
ls -l $(which gonzo)
# Should show: -rwxr-xr-x

Build Failures

Symptom: go install or make build fails.

Common causes:

Go version too old

# Check version (need 1.21+)
go version

# Update via Homebrew
brew upgrade go

# Or download from https://golang.org/dl/

Missing dependencies

# Clean and retry
go clean -modcache
go mod download
go install github.com/control-theory/gonzo/cmd/gonzo@latest

Network issues

# Use proxy if behind firewall
export GOPROXY=https://proxy.golang.org,direct
go install github.com/control-theory/gonzo/cmd/gonzo@latest

Display Issues

Garbled or Broken Interface

Symptom: Strange characters, broken borders, or corrupted display.

Solutions:

Check terminal compatibility
- ✅ Works well: iTerm2, Alacritty, Windows Terminal, GNOME Terminal, Kitty
- ⚠️ May have issues: Very old terminals, basic xterm

Enable UTF-8 encoding

# Add to shell profile
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

# Verify
locale

Check TERM variable

# Should show 256 color support
echo $TERM
# Should be: xterm-256color, screen-256color, etc.

# Set if incorrect
export TERM=xterm-256color

Use appropriate font
- Install a font with good Unicode support
- Recommended: JetBrains Mono, Fira Code, Cascadia Code, Hack

No Colors Displayed

Symptom: All text appears in same color, no syntax highlighting.

Solutions:

Check color support

# Test color capability
tput colors
# Should show 256

Force color mode

export TERM=xterm-256color
gonzo -f logs.log

Check NO_COLOR variable

# Unset if present
unset NO_COLOR

# Verify it's gone
env | grep NO_COLOR

Try different skin

# Some terminals work better with specific skins
gonzo --skin=github-light -f logs.log

Terminal Too Small

Symptom: Interface is cramped or panels overlap.

Solution:

Gonzo requires minimum terminal size of 80x24 characters.

# Check current size
tput cols  # Width
tput lines # Height

# Resize terminal to at least 80x24
# Or use fullscreen mode: Cmd/Ctrl + Enter (terminal dependent)

Recommended: 120x40 or larger for best experience.

Mouse Not Working

Symptom: Clicking doesn't select items or switch panels.

Solutions:

Verify terminal supports mouse
- Most modern terminals do
- Check terminal settings/preferences

Use keyboard navigation instead

Tab         - Switch panels
↑↓ or k/j   - Navigate items
Enter       - Select/open

Known limitations:
- SSH sessions may not pass mouse events
- Tmux/Screen require special configuration
- Some older terminals lack mouse support

Log Processing Issues

No Logs Appearing

Symptom: Gonzo starts but dashboard remains empty.

Diagnosis & Solutions:

Verify input source exists

# For files
ls -la application.log
file application.log

# Check file has content
wc -l application.log
head application.log

Check file permissions

# Ensure readable
chmod +r application.log

# Verify
cat application.log | head

Test with simple input

# Create test file
echo '{"level":"info","message":"test"}' | gonzo

# If this works, issue is with your log file

Check for active filters
- Press ESC to clear any filters
- Look for filter indicator in status bar

Verify stdin is producing output

# Test the source directly
kubectl logs deployment/app | head

# If empty, source is the problem

Logs Appear Truncated

Symptom: Long log lines are cut off or abbreviated.

Solutions:

Use horizontal scrolling
```
← → or h l  - Scroll left/right
```
Open detail view
```
Enter - View full log entry
```
Increase terminal width
- Make terminal wider
- Use full screen mode

Mixed Format Logs Not Parsing

Symptom: Some logs parse correctly, others show as plain text.

Explanation: Gonzo detects format per line. Mixed format files will show inconsistent parsing.

Solutions:

Pre-filter by format

# Extract only JSON lines
grep '^{' mixed.log | gonzo

# Or use jq
cat mixed.log | jq -c 'select(type == "object")' | gonzo

Use custom format

gonzo --format=my-custom-format -f logs.txt

Accept mixed display
- Structured logs: parsed as JSON/logfmt
- Unstructured logs: shown as plain text
- Both viewable, just different presentation

Logs Not Following in Real-Time

Symptom: Using --follow but new logs don't appear.

Diagnosis:

Verify file is being written

# In another terminal
tail -f /var/log/app.log

# Or watch file size
watch -n 1 'ls -lh /var/log/app.log'

Check auto-scroll status
- Press End to jump to latest and resume auto-scroll
- Look for FOLLOWING indicator in status bar
Verify Gonzo isn't paused
- Press Space to unpause if showing ⏸ PAUSED

Test follow with known-working source

# In terminal 1
gonzo -f /tmp/test.log --follow

# In terminal 2
while true; do echo "test $(date)" >> /tmp/test.log; sleep 1; done

Log Rotation Issues

Symptom: Logs stop appearing after log rotation.

Explanation: When files are rotated (moved/renamed), Gonzo may lose the file handle.

Solutions:

Restart Gonzo after rotation

# Simple approach
gonzo -f /var/log/app.log --follow

Use stdin with tail

# tail -F follows through rotation
tail -F /var/log/app.log | gonzo

For production: Use OTLP or log shipping

# More reliable for long-running monitoring
gonzo --otlp-enabled

Performance Issues

High CPU Usage

Symptom: Gonzo consumes excessive CPU.

Causes & Solutions:

Very high log volume

# Reduce update frequency
gonzo -f logs.log --update-interval=5s

# Default is 1s; try 2s, 5s, or 10s

Large buffer processing

# Reduce buffer sizes
gonzo -f logs.log --log-buffer=500 --memory-size=5000

Complex regex filters
- Simplify regex patterns
- Use simpler string matches when possible
AI analysis running
- AI queries can be CPU intensive
- Wait for analysis to complete
- Use lighter models (gpt-3.5-turbo vs gpt-4)

High Memory Usage

Symptom: Gonzo consumes too much RAM.

Solutions:

Reduce log buffer

# Default: 1000 entries
gonzo -f logs.log --log-buffer=500

Reduce frequency tracking

# Default: 10000 words
gonzo -f logs.log --memory-size=5000

Process logs in chunks

# Instead of entire file
tail -n 10000 large.log | gonzo

# Or specific time range
grep "2024-01-15" large.log | gonzo

Use config file for persistent settings

# ~/.config/gonzo/config.yml
log-buffer: 500
memory-size: 5000

Slow Performance with Large Files

Symptom: Gonzo is sluggish when loading large log files.

Solutions:

Pre-filter before Gonzo

# Filter by severity
grep -E "(ERROR|WARN)" large.log | gonzo

# Filter by time range
awk '/10:00/,/11:00/' large.log | gonzo

# Last N lines
tail -n 5000 large.log | gonzo

Use streaming instead of file

# Stream rather than load entire file
cat large.log | gonzo

Increase update interval
```
gonzo -f large.log --update-interval=3s
```

Split large files

# Split into smaller files
split -l 10000 large.log chunk_

# Analyze chunks individually
gonzo -f chunk_aa

Dashboard Not Updating

Symptom: Interface appears frozen, no updates.

Diagnosis:

Check if paused
- Look for ⏸ PAUSED in status bar
- Press Space to unpause

Verify input is flowing

# Check source directly
tail -f /var/log/app.log

Check update interval

# May be set very high
# Press 'u' to cycle to faster update

Try reset
```
# Press 'r' to reset dashboard
```
Restart Gonzo
- Sometimes a clean restart resolves issues
- q to quit, then restart

File Input Issues

Glob Pattern Not Working

Symptom: gonzo -f "/var/log/*.log" doesn't find expected files.

Solutions:

Always quote glob patterns

# ✅ Correct - Gonzo handles expansion
gonzo -f "/var/log/*.log"

# ❌ Wrong - Shell expands before Gonzo sees it
gonzo -f /var/log/*.log

Verify files exist
```
ls /var/log/*.log
```

Check permissions

# Ensure files are readable
ls -la /var/log/*.log

Use absolute paths

# More reliable than relative
gonzo -f "/var/log/*.log"  # ✅
gonzo -f "../logs/*.log"    # May have issues

Multiple File Sources Not Merging

Symptom: Only seeing logs from one file when multiple specified.

Solution:

# Specify each file/pattern separately
gonzo -f file1.log -f file2.log -f file3.log

# Multiple patterns work too
gonzo -f "/var/log/app/*.log" -f "/var/log/nginx/*.log"

Logs will be merged in the order received (by timestamp if available).

Cannot Read File - Permission Denied

Symptom: Error message about insufficient permissions.

Solutions:

Check file permissions
```
ls -la /var/log/app.log
```
Add read permission
```
chmod +r /var/log/app.log
```

Run with appropriate user

# If log requires special permissions
sudo gonzo -f /var/log/secure

Copy to accessible location

# Last resort
cp /var/log/app.log ~/app.log
gonzo -f ~/app.log

Configuration Issues

Config File Not Loading

Symptom: Settings in config file are ignored.

Diagnosis:

Check config location

# Default location
ls -la ~/.config/gonzo/config.yml

# Should exist and be readable

Verify YAML syntax

# Use yamllint if available
yamllint ~/.config/gonzo/config.yml

# Or check with cat
cat ~/.config/gonzo/config.yml

Common YAML mistakes

# ❌ Wrong - underscores not supported
log_buffer: 2000
update_interval: 2s

# ✅ Correct - use hyphens
log-buffer: 2000
update-interval: 2s

Specify config explicitly

gonzo --config ~/.config/gonzo/config.yml -f logs.log

Environment Variables Not Working

Symptom: Environment variables like GONZO_FILES are ignored.

Solutions:

Verify export

# Check if set
env | grep GONZO

# Set if missing
export GONZO_FILES="/var/log/app.log"

Add to shell profile

# For persistent settings
echo 'export GONZO_FILES="/var/log/app.log"' >> ~/.bashrc
source ~/.bashrc

Command line flags override env vars

# Flag takes precedence
GONZO_FILES="file1.log" gonzo -f file2.log
# Will use file2.log, not file1.log

Getting Additional Help

Enable Verbose Logging

For detailed troubleshooting:

# Run with verbose flag
gonzo -v -f application.log 2> gonzo-debug.log

# Check debug output
cat gonzo-debug.log

Gather System Information

When reporting issues, collect:

# System info
uname -a
echo $TERM
echo $SHELL

# Gonzo version
gonzo --version

# Go version (if relevant)
go version

# Terminal info
echo $COLUMNS x $LINES

Test with Minimal Example

Create a minimal reproduction:

# Simple test case
echo '{"level":"info","message":"test log"}' > test.log
gonzo -f test.log

# If this works, issue is with your specific logs

AI-Specific Issues - Troubleshooting AI integration
Log Format Issues - Problems with log parsing
GitHub Issues - Report bugs or request features

Can't find your issue? Search existing GitHub issues or open a new one.

PreviousTroubleshooting NextAI-Specific Issues

Last updated 2 months ago

Installation Problems

Command Not Found After Installation

Permission Denied When Running Binary

Build Failures

Display Issues

Garbled or Broken Interface

No Colors Displayed

Terminal Too Small

Mouse Not Working

Log Processing Issues

No Logs Appearing

Logs Appear Truncated

Mixed Format Logs Not Parsing

Logs Not Following in Real-Time

Log Rotation Issues

Performance Issues

High CPU Usage

High Memory Usage

Slow Performance with Large Files

Dashboard Not Updating

File Input Issues

Glob Pattern Not Working

Multiple File Sources Not Merging

Cannot Read File - Permission Denied

Configuration Issues

Config File Not Loading

Environment Variables Not Working

Getting Additional Help

Enable Verbose Logging

Gather System Information

Test with Minimal Example

Related Resources