Skip to main content
goose provides built-in diagnostic tools to help you troubleshoot issues, gather system information, and report bugs effectively. This guide covers how to use diagnostics, view logs, and collect information for debugging.

​
Generating Diagnostic Reports

Diagnostic reports bundle system information, session data, configuration files, and recent logs into a single ZIP file. This is invaluable for debugging issues or getting technical support.

​
Using the CLI

Generate diagnostics for a specific session using the goose session diagnostics command: 
# Generate diagnostics for a specific session
goose session diagnostics --session-id <session_id>

# Interactive selection (prompts you to choose a session)
goose session diagnostics

# Save to a custom location
goose session diagnostics --session-id <session_id> --output /path/to/diagnostics.zip
Find your session ID: First, list available sessions to get the session ID: 
goose session list
Example output: 
Available sessions:
abc123def - My coding session - 2024-01-15 14:30:22
xyz789ghi - Documentation work - 2024-01-15 10:15:45

​
Using goose Desktop

  1. In an active chat session, look for the diagnostics icon in the bottom toolbar
  2. Click the diagnostics button
  3. Review the information about what data will be collected
  4. Click Download to generate and save the bundle
  5. The ZIP file will be saved as diagnostics_{session_id}.zip
The diagnostics button is only available when you have an active session, as it needs a session ID to generate the bundle.

​
What’s Included in Diagnostics

The diagnostics ZIP file contains several components: 
diagnostics_abc123def.zip
├── logs/
│   ├── goose-2024-01-15.jsonl
│   ├── goose-2024-01-14.jsonl
│   └── ... (up to 10 recent log files)
├── session.json          # Your session messages
├── config.yaml          # Configuration files (if they exist)
├── system.txt           # System information
├── schedule.json        # Scheduled tasks (if any)
├── scheduled_recipes/   # Scheduled recipe files
└── prompts/             # Custom prompt templates

​
System Information

The system.txt file includes:
  • App Version: goose version number
  • OS: Operating system (macOS, Linux, Windows)
  • OS Version: Specific OS version
  • Architecture: CPU architecture (x86_64, arm64, etc.)
  • Provider: Configured LLM provider
  • Model: Selected model name
  • Enabled Extensions: List of active extensions
  • Timestamp: When the diagnostic was generated

​
Session Data

The session.json file contains your conversation history, including:
  • User messages
  • Assistant responses
  • Tool calls and results
  • Session metadata

​
Log Files

Log files are stored in JSONL format (one JSON object per line) and include:
  • Timestamped events
  • Error messages and stack traces
  • Extension activation/deactivation
  • Provider API calls
  • Tool execution details

​
When to Generate Diagnostics

Include diagnostic data when filing a bug report to help maintainers understand your environment and reproduce the issue.
Generate diagnostics immediately after a crash or error occurs to capture relevant log data.
Diagnostics can help identify slow operations, network timeouts, or resource constraints.
Review your config.yaml and system information to verify settings are correct.

​
Viewing Logs Manually

​
Log Locations

goose stores logs in different locations depending on your operating system: 
~/.local/state/goose/logs/

​
Log Structure

Logs are organized by component and date: 
logs/
├── cli/
│   ├── 2024-01-15/
│   │   └── goose.jsonl
│   └── 2024-01-14/
│       └── goose.jsonl
├── server/
│   └── 2024-01-15/
│       └── goose.jsonl
└── llm/
    └── 2024-01-15/
        └── goose.jsonl

​
Reading JSONL Logs

Logs use JSONL format for structured data. Each line is a valid JSON object: 
# View recent logs
tail -f ~/.local/state/goose/logs/cli/$(date +%Y-%m-%d)/goose.jsonl

# Pretty print logs with jq
cat ~/.local/state/goose/logs/cli/$(date +%Y-%m-%d)/goose.jsonl | jq .

# Filter for errors only
cat ~/.local/state/goose/logs/cli/$(date +%Y-%m-%d)/goose.jsonl | jq 'select(.level=="ERROR")'

​
Log Retention

goose automatically cleans up old logs:
  • Logs older than 14 days are automatically deleted
  • Only the 10 most recent log files are included in diagnostic bundles
  • This helps manage disk space while retaining recent troubleshooting data

​
Debugging Common Scenarios

​
Provider Connection Issues

Check provider configuration: 
# Verify your provider settings
cat ~/.config/goose/config.yaml | grep -A 5 GOOSE_PROVIDER

# Test configuration
goose configure
Review connection logs: Look for provider-specific errors in the LLM logs: 
grep -i "error\|failed" ~/.local/state/goose/logs/llm/$(date +%Y-%m-%d)/goose.jsonl

​
Extension Activation Failures

List enabled extensions: 
# Check system info
goose session diagnostics

# View extension configuration
cat ~/.config/goose/config.yaml | grep -A 20 extensions
Common extension issues:
  • Missing package runners (npx, uvx)
  • Network access blocked in corporate environments
  • Malicious package detection blocking installation
  • Incorrect command or arguments in configuration

​
Session Recovery

List all sessions: 
goose session list
Resume a previous session: 
goose session resume --session-id <session_id>
Export session data: 
goose session export --session-id <session_id> --output session-backup.json

​
Privacy Considerations

Diagnostic bundles may contain sensitive information:
  • API keys (if stored in config.yaml instead of keyring)
  • Session messages with your code or data
  • File paths revealing your directory structure
  • Custom prompt templates
Before sharing diagnostic data:
  1. Review the contents of the ZIP file
  2. Redact any sensitive information
  3. Consider using environment variables for secrets instead of configuration files
  4. Remove or sanitize session data if needed

​
Getting Help

If you’re still experiencing issues after reviewing diagnostics:
  1. Check Known Issues: Review the Known Issues page for common problems and solutions
  2. Search Community: Check Discord for similar issues
  3. File a Bug Report: Use the diagnostic data when reporting bugs on GitHub
  4. Ask the Community: Join our Discord community for real-time help

Build docs developers (and LLMs) love

Get started for freeTalk to us