# 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**

   ```bash
   # 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**

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

   # Or add current directory to PATH
   export PATH=$PATH:$(pwd)
   ```
3. **Verify installation**

   ```bash
   which gonzo
   gonzo --version
   ```

#### Permission Denied When Running Binary

**Symptom**: `permission denied` when trying to execute gonzo.

**Solution**:

```bash
# 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**

   ```bash
   # Check version (need 1.21+)
   go version

   # Update via Homebrew
   brew upgrade go

   # Or download from https://golang.org/dl/
   ```
2. **Missing dependencies**

   ```bash
   # Clean and retry
   go clean -modcache
   go mod download
   go install github.com/control-theory/gonzo/cmd/gonzo@latest
   ```
3. **Network issues**

   ```bash
   # 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**

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

   # Verify
   locale
   ```
3. **Check TERM variable**

   ```bash
   # 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**

   ```bash
   # Test color capability
   tput colors
   # Should show 256
   ```
2. **Force color mode**

   ```bash
   export TERM=xterm-256color
   gonzo -f logs.log
   ```
3. **Check NO\_COLOR variable**

   ```bash
   # Unset if present
   unset NO_COLOR

   # Verify it's gone
   env | grep NO_COLOR
   ```
4. **Try different skin**

   ```bash
   # 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.

```bash
# 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**

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

   # Check file has content
   wc -l application.log
   head application.log
   ```
2. **Check file permissions**

   ```bash
   # Ensure readable
   chmod +r application.log

   # Verify
   cat application.log | head
   ```
3. **Test with simple input**

   ```bash
   # 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**

   ```bash
   # 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**

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

   # Or use jq
   cat mixed.log | jq -c 'select(type == "object")' | gonzo
   ```
2. **Use custom format**

   ```bash
   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**

   ```bash
   # 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**

   ```bash
   # 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**

   ```bash
   # Simple approach
   gonzo -f /var/log/app.log --follow
   ```
2. **Use stdin with tail**

   ```bash
   # tail -F follows through rotation
   tail -F /var/log/app.log | gonzo
   ```
3. **For production**: Use OTLP or log shipping

   ```bash
   # 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**

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

   # Default is 1s; try 2s, 5s, or 10s
   ```
2. **Large buffer processing**

   ```bash
   # 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**

   ```bash
   # Default: 1000 entries
   gonzo -f logs.log --log-buffer=500
   ```
2. **Reduce frequency tracking**

   ```bash
   # Default: 10000 words
   gonzo -f logs.log --memory-size=5000
   ```
3. **Process logs in chunks**

   ```bash
   # 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**

   ```yaml
   # ~/.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**

   ```bash
   # 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**

   ```bash
   # Stream rather than load entire file
   cat large.log | gonzo
   ```
3. **Increase update interval**

   ```bash
   gonzo -f large.log --update-interval=3s
   ```
4. **Split large files**

   ```bash
   # 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**

   ```bash
   # Check source directly
   tail -f /var/log/app.log
   ```
3. **Check update interval**

   ```bash
   # May be set very high
   # Press 'u' to cycle to faster update
   ```
4. **Try reset**

   ```bash
   # 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**

   ```bash
   # ✅ 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**

   ```bash
   ls /var/log/*.log
   ```
3. **Check permissions**

   ```bash
   # Ensure files are readable
   ls -la /var/log/*.log
   ```
4. **Use absolute paths**

   ```bash
   # 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**:

```bash
# 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**

   ```bash
   ls -la /var/log/app.log
   ```
2. **Add read permission**

   ```bash
   chmod +r /var/log/app.log
   ```
3. **Run with appropriate user**

   ```bash
   # If log requires special permissions
   sudo gonzo -f /var/log/secure
   ```
4. **Copy to accessible location**

   ```bash
   # 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**

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

   # Should exist and be readable
   ```
2. **Verify YAML syntax**

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

   # Or check with cat
   cat ~/.config/gonzo/config.yml
   ```
3. **Common YAML mistakes**

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

   # ✅ Correct - use hyphens
   log-buffer: 2000
   update-interval: 2s
   ```
4. **Specify config explicitly**

   ```bash
   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**

   ```bash
   # Check if set
   env | grep GONZO

   # Set if missing
   export GONZO_FILES="/var/log/app.log"
   ```
2. **Add to shell profile**

   ```bash
   # For persistent settings
   echo 'export GONZO_FILES="/var/log/app.log"' >> ~/.bashrc
   source ~/.bashrc
   ```
3. **Command line flags override env vars**

   ```bash
   # 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:

```bash
# 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:

```bash
# 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:

```bash
# 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**](https://github.com/control-theory/gonzo/issues) - Report bugs or request features

{% hint style="info" %}
**Can't find your issue?** Search existing [GitHub issues](https://github.com/control-theory/gonzo/issues) or [open a new one](https://github.com/control-theory/gonzo/issues/new).
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.controltheory.com/controltheory-documentation/gonzo-docs/troubleshooting/common-issues.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.