Remote Debugging¶

Core Workbench services run inside Docker containers as compiled JARs. Remote debugging (JDWP) is the only way to step through core logic at runtime when you need to understand behaviour or diagnose configuration issues.

Why remote debugging is needed¶

You cannot run core Workbench services directly in your IDE — they are pre-compiled JARs delivered as a versioned dependency. Remote debugging lets you attach IntelliJ to a running Docker container and step through the core code exactly as it executes in the container.

Note

If you find a bug in core code, you cannot fix it yourself — raise a core change request ticket. Remote debugging is for understanding behaviour and diagnosing configuration issues only.

Step 1: Enable the debug port¶

In sendPD, edit docker-compose-windows.yaml. Find the riskwire-underwriting service definition and add a ports mapping:

ports:
  - "5005:5005"

Then restart the container via the sendPD startup script. Confirm port 5005 appears next to the riskwire-underwriting container in Docker Desktop or via docker ps.

Step 2: Configure IntelliJ¶

Go to Run > Edit Configurations
Add a new Remote JVM Debug configuration
Set Host to localhost and Port to 5005
Click Apply, then Debug (green bug icon)
The status bar should show Connected

Debugging multiple services simultaneously¶

To debug more than one service at once, map each container to a different external port:

# riskwire-underwriting
ports:
  - "5005:5005"

# risk-hub
ports:
  - "5006:5005"

Create a separate IntelliJ Remote JVM Debug configuration for each port. All services use port 5005 internally — differentiate them by the external port on your host machine.

Key classes to debug¶

Class	Method	Use for
`RiskActionInstanceService`	`getActionInstancesConfigurationByRisk(riskId)`	Why is an action not appearing?
`RiskActionDisplayExpressionHelper`	`isFullDisplayExpressionPassed(expression, context)`	Debugging display criteria expressions
`RiskOperationsHandlerImpl`	`processOperation(...)`	What happens when an operation is executed

Debugging display criteria expressions¶

Set a breakpoint in RiskActionDisplayExpressionHelper.isFullDisplayExpressionPassed
Reload the risk page in the browser to trigger expression evaluation
Inspect the expression and context variables at the breakpoint
Evaluate alternative expressions directly in the IntelliJ Evaluate Expression dialog

Unit testing expressions¶

// Create a mock risk with the desired state
Risk risk = buildTestRisk();

// Build the evaluation context for the risk, then evaluate
boolean result = riskActionDisplayExpressionHelper
    .isFullDisplayExpressionPassed(expression, context);

// Assert
assertTrue(result);

Debugging the client microservice¶

The client microservice runs directly in your IDE (not Docker). Debug it normally using the IntelliJ Debug button — no remote configuration needed.

Use this approach to trace the flow from an API request to the point where it calls a core service. Then switch to the remote debugger to continue stepping through core logic inside the Docker container.

Diagnosing configuration issues¶

When an error occurs, examine the stack trace in the riskwire-underwriting logs. The trace points to the specific class and method throwing the exception:

Set a breakpoint on that class in the JAR source (External Libraries in IntelliJ)
Reproduce the issue
Step through the logic to understand the cause

If the error is in the client microservice, use the normal IDE debugger. Only use remote debug for errors in core services.