Diagnostics and Debugging

Learn how to generate diagnostic reports and debug issues in goose

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

Before reporting bugs

Include diagnostic data when filing a bug report to help maintainers understand your environment and reproduce the issue.

Experiencing crashes or errors

Generate diagnostics immediately after a crash or error occurs to capture relevant log data.

Performance issues

Diagnostics can help identify slow operations, network timeouts, or resource constraints.

Configuration problems

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:

macOS/Linux

~/.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

Related Resources

• Known Issues - Common problems and solutions
• FAQ - Frequently asked questions
• Environment Variables - Configuration options
• Configuration Files - Config file reference