# 5.1 Troubleshooting

Before submitting an Issue, please provide the necessary information following this guide to help us locate and resolve the problem faster.

> [!NOTE]
> ⚠️ **Please update to the latest version of MaaFramework** and verify the issue still exists before submitting. Issues in older versions may have been fixed.  
> Also ensure all uploaded files (logs, debug images, etc.) are from the latest version.

## Working Directory

The log files, debug images, and other files mentioned below are located in the working directory. Please first identify your working directory:

| Scenario | Working Directory Location |
| -------- | ------------------------- |
| GUI Applications | Directory containing the executable |
| MaaDebugger | Current working directory (cwd) |
| VSCode Extension | Click "Open Maa Log" in the sidebar |
| Custom Integration | Depends on your `LogDir` setting |

## Log Files

Logs are critical for troubleshooting. Please provide the complete log file.

### Log Location

By default, the log file is located at: `<working_directory>/debug/maafw.log`

### Before Uploading

1. Open the log file and scroll to the end to verify the timestamp matches when the issue occurred
2. If the file is noticeably short (may have been flushed), also upload `debug/maafw.bak.log`

### Upload Requirements

- **Provide complete logs**: Upload the `.log` file directly; compress to `.zip` if too large
- **Avoid excerpts**: Self-extracted log snippets often miss critical context
- **Prefer clean logs**: If the issue is reproducible, consider deleting the original log and running once more to capture the latest problem log. This reduces noise and speeds up analysis. For intermittent issues, upload whatever you have
- **Comparison logs**: If one operation works normally while another fails, upload both logs and rename them for clarity (e.g., `maa_ok.log` / `maa_fail.log`). This helps identify differences quickly

## Pipeline Configuration

If the issue is related to task flow, please provide the relevant Pipeline JSON configuration:

- Complete definition of the problematic node
- Related preceding and following nodes (those referenced by `next`, `interrupt`, etc.)
- If there are many nodes, keep only the minimal set needed to reproduce the issue

Example:

```json
{
    "ProblemNode": {
        "recognition": "TemplateMatch",
        "template": "xxx.png",
        "threshold": 0.7,
        "action": "Click",
        "next": ["NextNode"]
    }
}
```

## Crash Issues

If the program crashes, please also provide the Crash Dump file:

- **Windows**: Usually located at `C:\Users\<Username>\AppData\Local\CrashDumps\`, file format is `.dmp`
- **Linux/macOS**: Check for core dump files, or obtain crash info from `dmesg` / system logs

Verify the dump file's modification date matches the crash time to avoid uploading unrelated historical dumps.

## Recognition Issues

Recognition-related issues require debug images and related image resources.

### Enable Debug Images

Set the following in `<working_directory>/config/maa_option.json`:

```json
{
    "save_draw": true
}
```

Once enabled, recognition visualization images are saved to `<working_directory>/debug/vision/`, with file naming format: `{node_name}_{reco_id}_{timestamp}.jpg`

Draw images annotate the original screenshot with ROI regions, recognition hit locations, and match details (e.g., template matching displays the template image and match score on the right side).

### Required Images

| Type | Description | Required |
| ---- | ----------- | -------- |
| Draw images | Debug images from `debug/vision/` directory | ✅ |
| Template images | Images referenced by `template` field in Pipeline (in `resource/image/`) | ✅ |
| Original screenshot | Complete screen capture when the issue occurred | Recommended |

Also describe the difference between expected and actual recognition results.

## Minimal Reproduction

Please provide a **minimal reproduction** whenever possible. This greatly accelerates problem identification.

- Reduced to only the minimum code and resources that trigger the issue
- Remove business logic and nodes unrelated to the problem
- Can run independently and reliably reproduce the issue

**Simple cases**: Post key code snippets and Pipeline JSON directly in the Issue  
**Complex cases**: Provide a runnable minimal project archive, or create a GitHub repository

## Issue Checklist

### General Issues

- [ ] Complete `maafw.log` log file
- [ ] Problem description (expected vs actual behavior)
- [ ] MaaFramework version
- [ ] Pipeline JSON (if related to task flow)

### Crash Issues (Additional)

- [ ] Crash Dump file (`.dmp`)
- [ ] **Exact MaaFramework version** (crash analysis depends on version-specific debug symbols)
- [ ] Steps taken before the crash

### Recognition Issues (Additional)

- [ ] Draw debug images from `debug/vision/`
- [ ] Pipeline JSON (recognition configuration of related nodes)
- [ ] Template images (if using TemplateMatch/FeatureMatch)
- [ ] Original screenshot (optional but recommended)

### Bonus Points

- [ ] Minimal reproduction project
- [ ] Steps to reproduce the issue

## Other Communication Channels

Besides GitHub Issues, you can also get help through:

- **QQ Group**: 595990173 (development discussions only)

For simple usage questions, consider asking in the group first. For complex bugs or feature requests, please submit an Issue.

## Submit an Issue

Please submit issues at [GitHub Issues](https://github.com/MaaXYZ/MaaFramework/issues).

The more complete information you provide, the faster the issue can be resolved. Thank you for your feedback!
