Fixing bugs is also an important part of development.
There are techniques to quickly and accurately locate, analyze, and resolve bugs.
This article will briefly introduce the general process of troubleshooting bugs.

Note

The following content is for reference only. Please pay attention to its timeliness.

Preparations

Communicate with the person who reported the bug to gather as much relevant information as possible, such as:

• Detailed description of the issue (time of occurrence, scenario, etc.)
• Necessary information like configuration files, logs, screenshots, etc.

Locating Key Logs

Using MaaLogAnalyzer for Log Analysis

Recommend using MaaLogAnalyzer for visual log analysis. It can:

• Automatically identify resource version and runtime mode (MaaPiCli/MFA)
• Visualize Pipeline execution flow
• Quickly locate errors and abnormal nodes
• Analyze node matching patterns and execution time

Usage Steps:

1. Download the latest version from Releases
2. Open the tool and import log files (debug/maa.log or logs from logs/ directory)
3. View the visual execution flow and locate problem nodes

Log File Locations

M9A logs are typically located at:

• debug/maa.log - MaaFramework core logs
• debug/custom/ - Logs generated by Custom modules
• debug/sink/ - Sink event listener logs (structured JSONL format) (Deprecated)
• logs/ - MFA logs (only when running with MFA)

Manual Analysis (Fallback)

If MaaLogAnalyzer is not available, you can manually analyze:

1. Confirm Version Information

   Search in maa.log for:

   • Interface Version: [data.version= - Check resource version
   • MFAA Version or MaaPiCli - Confirm runtime mode

2. Locate Issues

   • Task ends prematurely: Search for [ERR] to check error messages
   • Task loops: Search for reco hit to find abnormal matching patterns

Analyzing the Issue

Here, issues are roughly categorized into three types: resource loading issues, connection issues, and pipeline issues.

Resource Loading Issues

Resource loading failure caused by overwriting installation when renaming resources:

[2024-11-17 22:29:04.185][ERR][Px10564][Tx9380][PipelineResMgr.cpp][L211][MaaNS::ResourceNS::PipelineResMgr::parse_config] key already exists [key=OutsideDeduction]

Connection Issues

Simulator connection failure:

[2024-11-24 23:44:05.539][ERR][Px26056][Tx55883][ControlUnitMgr.cpp][L55][MaaNS::CtrlUnitNs::ControlUnitMgr::connect] failed to connect [adb_path_=D:/MuMu Player 12/shell/adb.exe] [adb_serial_=127.0.0.1:16384]

Pipeline Issues

These are the main issues M9A needs to focus on. Understanding the original pipeline process and analyzing the execution shown in the logs is necessary.

1. Non-pipeline process-related issues

   These issues are not caused by logical problems in the pipeline process itself.

   Based on the problematic node, there are two types:

   The first type is non-unconditional matching/inverse nodes.
   A common cause is that screenshots are taken too quickly, matching the next node, but the current screen has not stabilized yet.
   The solution is to add appropriate post_wait_freezes to the current node to wait for the screen to stabilize before making a judgment.

   The second type is unconditional matching/inverse nodes.
   This may occur when entering an unexpected interface, leading to incorrect judgments.
   The solution is to modify as needed.

2. Pipeline process-related issues

   These issues are due to the incompleteness of the task process itself and require modifications after analysis.

Resolving the Issue

Refer to Common Issues for the first two types of issues. For pipeline issues, modify based on the analysis results.

Verifying the Fix

After fixing, release a test version. If the test is successful, the issue is resolved.