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:

1. 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

2. 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)

3. 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:

1. Go version too old

   # Check version (need 1.21+)
   go version
   
   # Update via Homebrew
   brew upgrade go
   
   # Or download from https://golang.org/dl/

2. Missing dependencies

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

3. 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:

1. Check terminal compatibility

   • ✅ Works well: iTerm2, Alacritty, Windows Terminal, GNOME Terminal, Kitty

   • ⚠️ May have issues: Very old terminals, basic xterm

2. Enable UTF-8 encoding

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

3. Check TERM variable

   # Should show 256 color support
   echo $TERM
   # Should be: xterm-256color, screen-256color, etc.
   
   # Set if incorrect
   export TERM=xterm-256color

4. 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:

1. Check color support

   # Test color capability
   tput colors
   # Should show 256

2. Force color mode

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

3. Check NO_COLOR variable

   # Unset if present
   unset NO_COLOR
   
   # Verify it's gone
   env | grep NO_COLOR

4. 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:

1. Verify terminal supports mouse

   • Most modern terminals do

   • Check terminal settings/preferences

2. Use keyboard navigation instead

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

3. 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:

1. Verify input source exists

   # For files
   ls -la application.log
   file application.log
   
   # Check file has content
   wc -l application.log
   head application.log

2. Check file permissions

   # Ensure readable
   chmod +r application.log
   
   # Verify
   cat application.log | head

3. Test with simple input

   # Create test file
   echo '{"level":"info","message":"test"}' | gonzo
   
   # If this works, issue is with your log file

4. Check for active filters

   • Press ESC to clear any filters

   • Look for filter indicator in status bar

5. 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:

1. Use horizontal scrolling

   ← → or h l  - Scroll left/right

2. Open detail view

   Enter - View full log entry

3. 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:

1. Pre-filter by format

   # Extract only JSON lines
   grep '^{' mixed.log | gonzo
   
   # Or use jq
   cat mixed.log | jq -c 'select(type == "object")' | gonzo

2. Use custom format

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

3. 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:

1. 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'

2. Check auto-scroll status

   • Press End to jump to latest and resume auto-scroll

   • Look for FOLLOWING indicator in status bar

3. Verify Gonzo isn't paused

   • Press Space to unpause if showing ⏸ PAUSED

4. 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:

1. Restart Gonzo after rotation

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

2. Use stdin with tail

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

3. 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:

1. Very high log volume

   # Reduce update frequency
   gonzo -f logs.log --update-interval=5s
   
   # Default is 1s; try 2s, 5s, or 10s

2. Large buffer processing

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

3. Complex regex filters

   • Simplify regex patterns

   • Use simpler string matches when possible

4. 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:

1. Reduce log buffer

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

2. Reduce frequency tracking

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

3. 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

4. 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:

1. 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

2. Use streaming instead of file

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

3. Increase update interval

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

4. 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:

1. Check if paused

   • Look for ⏸ PAUSED in status bar

   • Press Space to unpause

2. Verify input is flowing

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

3. Check update interval

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

4. Try reset

   # Press 'r' to reset dashboard

5. 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:

1. 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

2. Verify files exist

   ls /var/log/*.log

3. Check permissions

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

4. 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:

1. Check file permissions

   ls -la /var/log/app.log

2. Add read permission

   chmod +r /var/log/app.log

3. Run with appropriate user

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

4. 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:

1. Check config location

   # Default location
   ls -la ~/.config/gonzo/config.yml
   
   # Should exist and be readable

2. Verify YAML syntax

   # Use yamllint if available
   yamllint ~/.config/gonzo/config.yml
   
   # Or check with cat
   cat ~/.config/gonzo/config.yml

3. Common YAML mistakes

   # ❌ Wrong - underscores not supported
   log_buffer: 2000
   update_interval: 2s
   
   # ✅ Correct - use hyphens
   log-buffer: 2000
   update-interval: 2s

4. 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:

1. Verify export

   # Check if set
   env | grep GONZO
   
   # Set if missing
   export GONZO_FILES="/var/log/app.log"

2. Add to shell profile

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

3. 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

Related Resources

• 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.