# 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 %}


---

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