# Troubleshooting

Having issues with Gonzo? You're in the right place! This section helps you diagnose and resolve common problems quickly.

### Quick Problem Solver

#### Installation Issues

**Problem**: Can't install or run Gonzo\
**Solution**: Common Issues - Installation

#### Display Problems

**Problem**: Broken UI, garbled text, or no colors\
**Solution**: Common Issues - Display

#### Logs Not Showing

**Problem**: Gonzo starts but no logs appear\
**Solution**: Common Issues - Log Processing

#### AI Not Working

**Problem**: AI features don't respond or show errors\
**Solution**: AI-Specific Issues

#### Format Not Parsing

**Problem**: Logs appear as plain text instead of structured\
**Solution**: Log Format Issues

#### Performance Issues

**Problem**: High CPU/memory usage or slow performance\
**Solution**: Common Issues - Performance

### Troubleshooting Guides

#### Common Issues

The most frequently encountered problems and their solutions:

**Installation & Setup**:

* Command not found
* Permission denied
* Build failures
* Shell completion

**Display & UI**:

* Garbled characters
* Missing colors
* Mouse not working
* Terminal too small

**Log Processing**:

* No logs appearing
* Logs not following
* Mixed format issues
* Slow processing

**Performance**:

* High CPU usage
* High memory usage
* Slow with large files
* Dashboard not updating

**Configuration**:

* Config file not loading
* Environment variables ignored
* Settings not applied

#### AI-Specific Issues

Troubleshooting AI integration and analysis features:

**General AI Problems**:

* AI features not working
* No response from AI
* Model selection empty
* Analysis returns errors

**OpenAI Issues**:

* Authentication failed
* Model access denied
* Rate limit errors
* API key problems

**LM Studio Issues**:

* Cannot connect
* Model not loading
* Wrong model selected
* URL format errors

**Ollama Issues**:

* Service not running
* Model not found
* Connection timeouts
* URL configuration

**Performance**:

* AI analysis very slow
* High memory with AI
* Provider timeouts

#### Log Format Issues

Problems with log parsing and format detection:

**Format Detection**:

* Logs not being parsed
* Mixed format logs
* Attributes not extracted
* Wrong format detected

**JSON Problems**:

* Malformed JSON
* Multi-line JSON
* JSON with metadata prefix
* Escaped JSON strings

**Logfmt Issues**:

* Logfmt not detected
* Spaces in values
* Nested structures

**Plain Text**:

* No structure extracted
* Severity not detected
* Custom format needed

**OTLP Format**:

* OTLP logs not appearing
* Attributes missing
* Connection issues

**Custom Formats**:

* Format not working
* Regex not matching
* Parser errors

### Diagnostic Tools

#### Check Your Setup

**Verify installation**:

```bash
# Check version
gonzo --version

# Check help
gonzo --help

# Test with simple input
echo '{"level":"info","msg":"test"}' | gonzo
```

**Check environment**:

```bash
# View configuration
env | grep GONZO
env | grep OPENAI

# Check terminal
echo $TERM
echo $LANG
```

**Test components**:

```bash
# Test file input
gonzo -f test.log

# Test OTLP receiver
gonzo --otlp-enabled

# Test AI (if configured)
# Press 'i' on a log entry
```

#### Enable Debug Mode

Get detailed troubleshooting information:

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

# Check debug output
tail -f debug.log
```

#### Collect System Information

When reporting issues, gather this information:

```bash
# System details
uname -a
echo $TERM

# Gonzo version
gonzo --version

# Go version (if building from source)
go version

# Configuration
cat ~/.config/gonzo/config.yml

# Environment variables
env | grep -E '(GONZO|OPENAI|TERM|LANG)'
```

### Common Patterns

#### Error Messages

**"command not found"**

**Meaning**: Gonzo is not in your PATH\
**Fix**: Installation Issues

**"permission denied"**

**Meaning**: File is not executable or not readable\
**Fix**: Permission Issues

**"invalid API key"**

**Meaning**: OpenAI API key is incorrect or missing\
**Fix**: AI Issues - Authentication

**"address already in use"**

**Meaning**: OTLP port is already taken\
**Fix**: Common Issues - OTLP

**"cannot parse JSON"**

**Meaning**: Log format is invalid\
**Fix**: Format Issues - JSON

#### Behavior Patterns

**Logs appear but no structure**

**Symptom**: Everything shows as plain text\
**Likely cause**: Format not detected\
**Solution**: Format Detection Issues

**Works locally, fails in container**

**Symptom**: Different behavior in Docker/Kubernetes\
**Likely cause**: Environment or terminal differences\
**Solution**: Check environment variables and terminal settings

**Intermittent failures**

**Symptom**: Sometimes works, sometimes doesn't\
**Likely cause**: Race condition or timing issue\
**Solution**: Check logs with verbose mode, report to GitHub

**Slow performance after time**

**Symptom**: Starts fast, gets slower over time\
**Likely cause**: Buffer full, memory pressure\
**Solution**: Performance Issues

### Troubleshooting Workflow

Follow this systematic approach:

#### 1. Identify the Problem

**Questions to ask**:

* What were you trying to do?
* What actually happened?
* When did it start happening?
* Can you reproduce it?
* What error messages appear?

#### 2. Check the Basics

**Quick checks**:

* ✅ Is Gonzo installed and in PATH?
* ✅ Is the log file readable?
* ✅ Is the terminal adequate?
* ✅ Are environment variables set?
* ✅ Is the config file valid?

#### 3. Review Relevant Guide

**Match your issue**:

* Installation/setup → Common Issues
* AI features → AI-Specific Issues
* Log parsing → Log Format Issues

#### 4. Try Solutions

**Test systematically**:

* Try simplest solution first
* Test one change at a time
* Document what works
* Verify the fix persists

#### 5. Get Help

**If still stuck**:

* Search [GitHub Issues](https://github.com/control-theory/gonzo/issues)
* Check [GitHub Discussions](https://github.com/control-theory/gonzo/discussions)
* Ask in community channels
* Open a new issue with details

### Prevention Tips

#### Avoid Common Mistakes

**Installation**:

* ✅ Use correct Go version (1.21+)
* ✅ Add Gonzo to PATH
* ✅ Set proper permissions

**Configuration**:

* ✅ Quote glob patterns
* ✅ Use valid YAML syntax
* ✅ Check file paths are absolute
* ✅ Verify API keys are correct

**Log Files**:

* ✅ Ensure files are readable
* ✅ Use consistent log format
* ✅ Avoid mixing formats in same file

**AI Integration**:

* ✅ Set API key correctly
* ✅ Use correct API base URL
* ✅ Check provider-specific requirements

**OTLP**:

* ✅ Use standard ports (4317, 4318)
* ✅ Match protocol (gRPC vs HTTP)
* ✅ Verify endpoint URLs

#### Best Practices

**For reliability**:

* Use config files for persistent settings
* Test with small samples first
* Monitor resource usage
* Keep Gonzo updated

**For debugging**:

* Enable verbose mode when testing
* Save debug output
* Create minimal reproduction cases
* Document your setup

**For performance**:

* Adjust buffer sizes appropriately
* Increase update interval if needed
* Filter logs before Gonzo when possible
* Monitor memory usage

### Getting Additional Help

#### Documentation

**Reference guides**:

* Common Issues - General troubleshooting
* AI-Specific Issues - AI integration
* Log Format Issues - Parsing problems
* Configuration Reference - Config options
* Environment Variables - Env var reference

#### Community Support

**Ask for help**:

* **GitHub Discussions**: <https://github.com/control-theory/gonzo/discussions>
* **GitHub Issues**: <https://github.com/control-theory/gonzo/issues>
* **Email**: <support@controltheory.com>

**When asking for help, include**:

* Gonzo version (`gonzo --version`)
* Operating system and version
* What you're trying to do
* What actually happens
* Error messages (if any)
* Minimal reproduction steps
* Sample logs (sanitized)

#### Reporting Bugs

**Before reporting**:

1. Search existing issues
2. Update to latest version
3. Test with minimal configuration
4. Create reproduction steps

**Good bug report includes**:

* Clear title
* Detailed description
* Steps to reproduce
* Expected vs actual behavior
* Environment details
* Logs and screenshots

**Template**:

```markdown
**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
1. Run command '...'
2. Press key '...'
3. See error

**Expected behavior**
What you expected to happen.

**Environment:**
- OS: [e.g., macOS 14.0]
- Gonzo Version: [e.g., 0.1.6]
- Go Version: [e.g., 1.21.5]
- Terminal: [e.g., iTerm2]

**Logs/Screenshots**
[Attach relevant output]
```

[Open an issue →](https://github.com/control-theory/gonzo/issues/new)

### Known Issues

#### Current Known Issues

Check [GitHub Issues](https://github.com/control-theory/gonzo/issues) for the latest list of known issues.

**Common known issues**:

* Some older terminals have limited mouse support
* Very large OTLP batches may cause memory spikes
* Custom format regex can be slow with complex patterns

See Changelog for issues fixed in recent releases.

### Quick Reference

#### Troubleshooting Checklist

When something goes wrong:

* [ ] Check Gonzo is installed: `gonzo --version`
* [ ] Verify file/input exists and is readable
* [ ] Check terminal is adequate (80x24 min, 256 colors)
* [ ] Review environment variables: `env | grep GONZO`
* [ ] Test with minimal example
* [ ] Check relevant troubleshooting guide
* [ ] Enable verbose mode: `gonzo -v`
* [ ] Search existing issues
* [ ] Ask for help if needed

#### Most Common Fixes

**90% of issues are solved by**:

1. Adding Gonzo to PATH
2. Using proper file permissions
3. Setting environment variables correctly
4. Using valid configuration syntax
5. Updating to latest version

***

### Start Troubleshooting

Choose the guide that matches your problem:

**📋 Common Issues** - General problems and solutions

**🤖 AI-Specific Issues** - AI integration troubleshooting

**📝 Log Format Issues** - Parsing and format problems

{% hint style="info" %}
**Quick tip**: Most problems can be diagnosed by running `gonzo -v` to enable verbose mode. Check the output for detailed error messages.
{% endhint %}

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