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/maa.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/maa.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:

{
    "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:

{
    "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 maa.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.

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