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:
# Check version
gonzo --version
# Check help
gonzo --help
# Test with simple input
echo '{"level":"info","msg":"test"}' | gonzoCheck environment:
# View configuration
env | grep GONZO
env | grep OPENAI
# Check terminal
echo $TERM
echo $LANGTest components:
# Test file input
gonzo -f test.log
# Test OTLP receiver
gonzo --otlp-enabled
# Test AI (if configured)
# Press 'i' on a log entryEnable Debug Mode
Get detailed troubleshooting information:
# Run with verbose flag
gonzo -v -f application.log 2> debug.log
# Check debug output
tail -f debug.logCollect System Information
When reporting issues, gather this information:
# 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
Check GitHub 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: [email protected]
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:
Search existing issues
Update to latest version
Test with minimal configuration
Create reproduction steps
Good bug report includes:
Clear title
Detailed description
Steps to reproduce
Expected vs actual behavior
Environment details
Logs and screenshots
Template:
**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]Known Issues
Current Known Issues
Check GitHub 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:
Most Common Fixes
90% of issues are solved by:
Adding Gonzo to PATH
Using proper file permissions
Setting environment variables correctly
Using valid configuration syntax
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
Can't find your issue? Search GitHub Issues or open a new one with details about your problem.
Last updated