> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/block/goose/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
# 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:

```bash theme={null}
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`

<Note>
  The diagnostics button is only available when you have an active session, as it needs a session ID to generate the bundle.
</Note>

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

<AccordionGroup>
  <Accordion title="Before reporting bugs">
    Include diagnostic data when filing a bug report to help maintainers understand your environment and reproduce the issue.
  </Accordion>

  <Accordion title="Experiencing crashes or errors">
    Generate diagnostics immediately after a crash or error occurs to capture relevant log data.
  </Accordion>

  <Accordion title="Performance issues">
    Diagnostics can help identify slow operations, network timeouts, or resource constraints.
  </Accordion>

  <Accordion title="Configuration problems">
    Review your `config.yaml` and system information to verify settings are correct.
  </Accordion>
</AccordionGroup>

## Viewing Logs Manually

### Log Locations

goose stores logs in different locations depending on your operating system:

<CodeGroup>
  ```bash macOS/Linux theme={null}
  ~/.local/state/goose/logs/
  ```

  ```powershell Windows theme={null}
  %LOCALAPPDATA%\Block\goose\logs\
  ```
</CodeGroup>

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

```bash theme={null}
# 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:**

```bash theme={null}
# 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:

```bash theme={null}
grep -i "error\|failed" ~/.local/state/goose/logs/llm/$(date +%Y-%m-%d)/goose.jsonl
```

### Extension Activation Failures

**List enabled extensions:**

```bash theme={null}
# 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:**

```bash theme={null}
goose session list
```

**Resume a previous session:**

```bash theme={null}
goose session resume --session-id <session_id>
```

**Export session data:**

```bash theme={null}
goose session export --session-id <session_id> --output session-backup.json
```

## Privacy Considerations

<Warning>
  **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
</Warning>

## Getting Help

If you're still experiencing issues after reviewing diagnostics:

1. **Check Known Issues**: Review the [Known Issues](/troubleshooting/known-issues) page for common problems and solutions
2. **Search Community**: Check [Discord](https://discord.gg/goose-oss) for similar issues
3. **File a Bug Report**: Use the diagnostic data when [reporting bugs on GitHub](https://github.com/block/goose/issues/new?template=bug_report.md)
4. **Ask the Community**: Join our [Discord community](https://discord.gg/goose-oss) for real-time help

## Related Resources

* [Known Issues](/troubleshooting/known-issues) - Common problems and solutions
* [FAQ](/troubleshooting/faq) - Frequently asked questions
* [Environment Variables](/guides/environment-variables) - Configuration options
* [Configuration Files](/configuration) - Config file reference