9.1 Microflow Debugger & Diagnostic Tools

9.1 Microflow Debugger & Diagnostic Tools

Exam Focus: The Mendix Certified Intermediate Developer exam thoroughly tests your practical mastery of the Studio Pro microflow debugger. You must understand the underlying architecture of the debugging engine, how to configure standard and conditional breakpoints, the precise behavior of execution stepping controls (Step Into, Step Over, Step Out), how to interpret in-memory object states in the Variables and Debugger panes, and the operational hazards of attaching a remote debugger to shared cloud environments.

Building sophisticated enterprise low-code applications requires rigorous diagnostic tools. When microflows execute complex calculations, invoke REST integrations, or handle multi-entity database transactions, visual inspection of the model alone is insufficient to identify runtime defects. The Mendix Studio Pro Debugger enables developers to pause microflow execution, inspect variables in active memory before they are committed, step through logic branch by branch, and isolate subtle defects without altering application code.

---

Studio Pro Debugger Architecture & Runtime Execution

The Mendix debugger is not merely a visual simulation; it is an active diagnostic client connected directly to the Mendix Runtime Engine:

The Runtime Debugging Channel

When you start an application locally (or enable debugging on a cloud node), the Mendix Runtime starts an internal administrative debugging service listening on a dedicated port. Studio Pro communicates with this service over HTTP/TCP:

• Thread Suspension: When the runtime encounters an activity with an active breakpoint, it suspends the specific Java worker thread executing that microflow request.
• Transaction Boundary Preservation: The database transaction associated with that microflow remains open in an uncommitted state. Database locks acquired by earlier activities (such as row-level write locks) remain held while execution is paused.
• Stateless Client Polling: Studio Pro periodically polls the runtime debugging endpoint to detect paused threads, retrieve active variable values, and send execution commands (such as Step Over or Continue).

Breakpoint Placement Rules

In Mendix Studio Pro, breakpoints can be toggled on specific microflow elements:

• Permitted Elements: Microflow activities (action activities, sub-microflow calls, retrieves, commits), Decision splits, Loops, and Merge points.
• Prohibited Elements: Breakpoints cannot be placed on Start events, End events, Error End events, or Sequence flows (the connecting lines between activities).

[Start Event] ──> [Retrieve Order] ──> [🔴 Breakpoint: Calculate Tax] ──> [End Event]
                                              │
                                    Execution Pauses Here:
                             - Current Activity has NOT run yet
                             - Input variables are in memory
                             - Output variable does not yet exist

---

Granular Stepping Execution: Step Into, Step Over, and Step Out

Once execution pauses at a breakpoint, Studio Pro brings the Debugger pane and the active microflow canvas to the foreground. Navigate the logic with the toolbar buttons or the documented shortcut keys. Every debugger shortcut in Studio Pro is an Alt + F-key combination (on macOS, Option + Fn + the same F-key) — a favourite exam detail, because the bare F-keys are bound to unrelated commands such as Create deployment package (F7) and Next error (F8):

1. Step over (Alt + F6)

• Mechanic: Executes the currently highlighted activity and advances the pause indicator to the next activity within the same flow.
• Sub-microflow behaviour: If the current activity is a Sub-microflow call, Step over runs the entire sub-microflow — including its loops and nested calls — at full speed and pauses at the next activity in the parent. The sub-microflow canvas is not opened unless a breakpoint inside it is hit.
• Use case: You trust the sub-microflow and only care about its output in the parent flow.

2. Step into (Alt + F5)

• Mechanic: Descends into the sub-microflow, sub-nanoflow, or loop being called and pauses at its first activity.
• Primitive activity behaviour: On an ordinary activity such as Change variable or Retrieve, Step into behaves like Step over — it executes the activity and advances.
• Use case: Debugging faulty logic nested inside child sub-microflows.

3. Step out (Alt + F7)

• Mechanic: Runs the remainder of the current sub-flow or loop, returns control to the caller, and pauses at the activity following the call.
• Use case: You have stepped in, confirmed the logic is fine, and want to return to the parent without walking through the rest.

4. Continue (Alt + F8) and Continue all (Alt + F9)

• Continue resumes the currently paused flow until the next enabled (or satisfied conditional) breakpoint, or until the flow ends.
• Continue all resumes every currently paused microflow or nanoflow at once — the command you want when several users' requests have queued up behind a shared breakpoint on a multi-user environment.

Inspecting In-Memory State: The Debugger, Variables & Breakpoints Panes

Studio Pro exposes three panes for debugging. Note that there is no separate "Call Stack" pane — the chain of paused flows lives in the Debugger pane:

The Debugger Pane

The Debugger pane is where you step through execution. It lists the microflows and nanoflows that are currently paused together with the chain of calls that led to the current activity, so you can see that ACT_SubmitOrder called SUB_CalculateLineDiscount. Selecting an entry in that chain re-points the Variables pane at the scope of the selected flow.

The Variables Pane

The Variables pane displays all the variables, objects, and lists involved in the paused microflow or nanoflow, and refreshes with every step you take:

• Primitive variables: Strings, Integers, Decimals, Booleans, and DateTimes with their name, type, and current value.
• Entity objects: Object ID, entity type (for example Sales.Order), and an expandable tree of every attribute currently held in runtime memory.
• Uncommitted memory vs. database values: The pane shows in-memory values. If a Change object activity set $Order/OrderStatus to Shipped without committing, the pane shows Shipped while the database row still reads Pending.
• Associations and lists: Expandable nodes reveal referenced objects and reference sets; list variables show their entity type and element count (for example List of Sales.OrderItem (4 items)).

The Breakpoints Pane

The Breakpoints pane lists every microflow and nanoflow that contains a breakpoint, which makes them easy to find again. From this pane you can enable, disable, and delete breakpoints, and configure their conditions.

---

Conditional Breakpoints: Expression-Based Diagnostic Triggers

In high-volume batch processing or loops processing thousands of records, pausing on every iteration is impractical. A Conditional Breakpoint instructs the Mendix Runtime to evaluate an expression each time the activity is reached and only suspend execution when the expression evaluates to true.

Configuring Conditional Breakpoints

1. Right-click an activity in Studio Pro and select Edit Breakpoint Condition... (or open the Breakpoints pane).
2. Author a standard Mendix microflow expression that returns a Boolean.
3. The runtime evaluates this expression in memory within the local variable scope of that activity.

Practical Conditional Expressions

• Isolating Specific Business Entities:

  $Order/OrderNumber = 'ORD-2026-9942'
  

• Detecting Threshold Anomalies:

  $AccountBalance/Amount < 0 and $Customer/VIPStatus = true
  

• Catching Null or Empty References:

  $Invoice/Invoice_Customer = empty
  

• Loop Counter Targeting:

  $IteratorCounter > 500
  

Exam Trap: If a conditional breakpoint contains an invalid expression (such as referencing a variable that is not in scope, or dividing by zero), the Mendix Runtime will log an evaluation error and either fail open or disable the breakpoint. Always verify that variables referenced in the condition exist at that exact point in the microflow.

---

Local vs. Remote Debugging: Mechanics, Security & Cloud Hazards

While local debugging (running inside Studio Pro against a local database) is completely isolated, Mendix also supports Remote Debugging against deployed environments (such as Acceptance, Test, or Sandbox clouds).

Establishing a Remote Debugging Connection

1. Enable the debugger on the environment: Open the app in the portal, go to Environments, click Details for the target environment, open the Debugger tab, and click Enable Debugger. Confirm the generated strong password (Mendix recommends not changing it) and apply the changes — the app restarts. The tab then shows the debugger URL and Password, each with a copy-to-clipboard link.
2. Connect from Studio Pro: Choose Run > Connect Debugger…, or click Connect… in the Debugger pane.
3. Credentials: Select An app running in Mendix Cloud or on another remote server, then paste the URL and password from the Debugger tab. (The debugger endpoint itself is {appURL}/debugger/.)
4. Model Alignment: Studio Pro verifies that the local .mpr project model matches the deployment package running on the remote server. If the models diverge, breakpoints will not bind correctly to remote activities.

Severe Operational Risks of Remote Debugging

Remote debugging on shared environments—especially Production or active Multi-User Acceptance environments—carries extreme operational risks:

1. Thread and Connection Starvation: When a breakpoint pauses execution, the worker thread is frozen. If the microflow holds an open database transaction, relational database locks (such as row locks on customer accounts) are held indefinitely until the developer steps or resumes. Other concurrent users attempting to modify those records will freeze and fail with LockTimeoutException.
2. Gateway Timeouts (HTTP 504): Web application ingress proxies (such as Nginx, Cloudflare, or AWS ALB) enforce strict request timeout limits (typically 60 to 120 seconds). If you leave an execution paused at a breakpoint longer than the gateway timeout, the proxy terminates the HTTP connection to the user's browser, returning an HTTP 504 Gateway Timeout. Even if you resume the flow later, the client has already disconnected.
3. End-User Freezing: If remote debugging is enabled on an environment where multiple team members or business testers are working, hitting a non-conditional breakpoint will catch any user's transaction that triggers the flow, effectively hijacking and stalling their session.

Best Practice Rule: Never connect a remote debugger to a Production environment under normal business operations. If remote debugging is unavoidable on an Acceptance environment, always use Conditional Breakpoints targeted strictly to your own test user account (e.g., $CurrentUser/Name = 'tester_ranchen').