aaif-goose--goose/documentation/docs/troubleshooting/diagnostics-and-reporting.md

title, sidebar_label, description

title	sidebar_label	description
Diagnostics and Reporting	Diagnostics and Reporting	Use built-in diagnostics, report bugs, and request new features with goose's integrated support tools.

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import { PanelLeft, Bug, MessageSquarePlus, Download } from 'lucide-react';

goose provides several built-in features to help you get support, report issues, and request new functionality. This guide covers the diagnostics system, bug reporting, and feature request tools.

Feature	Purpose	Location	Output
Diagnostics	Generate troubleshooting data	Chat input toolbar	JSON report with system info, logs, and session data
Report a Bug	Submit bug reports	Chat input toolbar OR Settings → App → Help & feedback	Opens GitHub issue template
Request a Feature	Suggest new features	Settings → App → Help & feedback	Opens GitHub issue template

Diagnostics System

The diagnostics feature creates a comprehensive troubleshooting JSON report that includes system information, session data, configuration files, and recent logs. This is invaluable for debugging issues or getting technical support.

Generating Diagnostics

1. In an active chat session, look for the icon in the bottom toolbar 2. Click the diagnostics button 3. Review the information in the modal about what data will be collected 4. Click `Download` to generate and save the diagnostics report 5. The JSON file will be saved as `diagnostics_{session_id}.json`

You can use `scripts/diagnostics-viewer.py` to inspect downloaded diagnostics reports; by default it looks in `~/Downloads`.

:::tip
The diagnostics button is only available when you have an active session, as it needs a session ID to generate the bundle.
:::

Use the session diagnostics command to generate a troubleshooting bundle. For complete details and all available options, see the [CLI Commands guide](/docs/guides/goose-cli-commands#session-diagnostics-options).

```sh
# 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.json
```

To find your session ID, first list available sessions:

```sh
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 Diagnostics Data

The diagnostics JSON file contains structured sections:

{
  "system": {},
  "session": {},
  "config": {},
  "logs": {},
  "prompts": [],
  "schedule": {},
  "errors": []
}

When to generate diagnostics:

• Experiencing crashes or unexpected behavior
• Getting error messages you don't understand
• Performance issues or slow responses
• Before reporting bugs to include technical details

What's included in diagnostics:

• System Information: App version, operating system, architecture, and timestamp
• Session Data: Your current conversation messages and history
• Configuration Files: Your configuration files (if they exist)
• Log Files: Recent application logs for debugging

:::warning Privacy Notice Diagnostics bundles contain your session messages and system information. If your session includes sensitive data (API keys, personal information, proprietary code), review the contents before sharing publicly. :::

Bug Reports

The bug report feature opens a structured GitHub issue template to help you provide all necessary information for effective bug reporting.

Creating Bug Reports

1. In an active chat session, look for the icon in the bottom toolbar 2. Click the diagnostics button 3. Click `File Bug on GitHub` 4. This opens GitHub in your browser with a pre-filled bug report template For CLI users, navigate directly to the GitHub repository:

```
https://github.com/aaif-goose/goose/issues/new?template=bug_report.md
```

Feature Requests

The feature request system helps you suggest improvements and new functionality for goose.

Submitting Feature Requests

1. Click the button in the top-left to open the sidebar 2. Click `Settings` in the sidebar 3. Click the `App` tab 4. Scroll down to the `Help & feedback` section 5. Click `Request a Feature` 6. This opens GitHub in your browser with a feature request template Navigate directly to the GitHub repository:

```
https://github.com/aaif-goose/goose/issues/new?template=feature_request.md
```

Error Recovery with "Ask goose"

When certain types of error occur in goose Desktop (such as failures to activate extensions), you'll see an Ask goose button in the error notification. This feature lets you quickly troubleshoot the issue with goose's help:

1. When the error occurs, an Ask goose button appears in the error notification
2. Click the button to send the error details to goose in a chat prompt
3. goose provides diagnostic suggestions and potential solutions

Additional Debugging

For issues not resolved by diagnostics:

• Session and System Logs: View detailed logs for debugging individual sessions
• Telemetry Export: Configure telemetry for performance analysis and production monitoring