Debug Task Constructor Planning Pipelines
MoveIt Task Constructor (MTC) planning pipelines perform a large-scale search for feasible solutions across numerous candidates. Some candidates are expected to fail (e.g., due to unreachable targets), while others may succeed. MTC systematically explores all options to determine a sequence of feasible steps needed to complete the task.
When MTC fails to find a solution —or even when it succeeds— introspecting intermediate solutions and identifying points of failure is often essential.
MTC pipelines are planned with the PlanMTCTask Behavior (see the Pick and Place tutorial using MTC for details).
Once that Behavior is executed, the details of the candidates that MTC evaluated are available for introspection.
MoveIt Pro includes a Task Constructor Debugger that works in both the desktop app and MoveIt Pro Cloud (which is simulation only and cannot be connected to robot hardware).
After running an Objective that uses PlanMTCTask, open it by selecting Task Constructor Debugger from the Mode menu in the top left, by clicking the debugger icon on a PlanMTCTask Behavior in the Behavior Tree view pane, or — when planning has just failed — with the Inspect failed plan in Task Constructor Debugger link on the error alert itself.
The debugger opens as a left sidebar listing the session's planning iterations; selecting one shows its stage tree with each stage's success and failure counts and compute time, the solutions for the selected stage with their cost and comments explaining why individual candidates failed, and the selected stage's properties.
It opens on the stage where planning ran out of solutions, rather than on the first stage, so a failed plan lands on the stage that caused it.
Select a solution to preview its trajectory in the 3D Visualizer.
Disabling introspection to reduce memory
The debugging described above relies on MTC introspection, which is enabled by default. With introspection on, each MTC task retains everything it evaluated (every successful and failed candidate, and the planning scene captured at each one). Each use of an MTC planning Subtree in an Objective holds its own task, and on versions before 10.2 that data is kept until the next Objective is loaded, not just until the run ends — so an Objective with many planning Subtrees, or a single task over a large planning scene, could consume a large amount of memory, in extreme cases exhausting it.
From MoveIt Pro 10.2, this retention is bounded by default: only the most recently planned MTC tasks (10 unless configured otherwise) keep their introspection data, and older tasks release theirs automatically as newer tasks are planned. Memory no longer grows with the number of planning Subtrees in an Objective. Released tasks behave like tasks planned with introspection disabled: SaveMTCTaskInspection skips them with a warning, so place it right after the PlanMTCTask it should capture rather than at the end of a long Objective.
The limit is configurable per robot configuration package with the mtc_introspection_retained_tasks key in the objectives section of config.yaml (see the config.yaml reference). Raise it to keep more planning iterations inspectable, lower it (down to 0, which releases each task's data as soon as planning completes) to reduce memory further:
objectives:
mtc_introspection_retained_tasks: 10
The InitializeMTCTask Behavior also exposes an enable_introspection input port (default true). Set it to false on a task to free its stored planning scenes and solutions as soon as planning completes (whether it succeeds or fails), without waiting for newer tasks to push it out of retention.
Disabling introspection turns off MTC debugging for that task: it still appears in the Task Constructor Debugger's Planning Iterations list, but selecting it reports a load failure instead of the plan, and SaveMTCTaskInspection will skip it. It also makes a failed plan's alert less detailed: you still see which stage failed and its attempt counts, but not the specific per-stage reason (for example the collision or IK message). Leave introspection enabled while you develop an Objective, disable it on tasks you no longer need to inspect once they are stable, and re-enable it for a single Subtree when you need to debug that task again.
For more ways to keep an Objective's memory bounded, see Keep Memory Bounded in Large Objectives.