troubleshooting.md

Troubleshooting

Startup Failure: Invalid jsonrpc.* Property

Symptom:

• Application fails at startup with IllegalArgumentException related to jsonrpc.*.

Cause:

• Fail-fast configuration validation rejects invalid values.

Checks:

• jsonrpc.path starts with / and has no whitespace
• jsonrpc.max-batch-size > 0
• jsonrpc.max-request-bytes > 0
• jsonrpc.validation.request.params-type-violation-code-policy is set to a valid enum value
• allowlist/denylist entries are not blank
• jsonrpc.notification-executor-bean-name is not null

Method Returns -32601 Method not found

Possible causes:

• Method not registered (annotation scan disabled or bean not detected)
• Method blocked by allowlist/denylist policy
• Method name mismatch between request and registration

Checks:

• jsonrpc.scan-annotated-methods value
• @JsonRpcMethod name or registration name
• jsonrpc.method-allowlist / jsonrpc.method-denylist

Params Return -32602 or -32600

Possible causes:

• params shape does not match method signature
• Missing named argument in object mode
• Positional array size mismatch
• Jackson conversion failure for target type
• Custom JsonRpcRequestValidator policy maps params-shape errors to -32600

Checks:

• For multi-arg object params, confirm @JsonRpcParam names
• For reflection names, ensure build uses -parameters
• Validate incoming JSON types
• Confirm jsonrpc.validation.request.params-type-violation-code-policy matches expected code semantics

Notification Did Not Return Body

This is expected JSON-RPC behavior when id is omitted.

If response is required, include id in request.

Executor Configuration Not Applied

Symptom:

• Notifications still appear synchronous.

Checks:

• jsonrpc.notification-executor-enabled=true
• named executor bean exists if notification-executor-bean-name is set
• if multiple executors exist, choose one explicitly

Parse Errors for Empty or Whitespace Body

Behavior:

• Empty/whitespace-only payload is treated as parse error (-32700).

Action:

• Ensure clients send valid JSON request object or batch array.

Oversized Payload Error

Behavior:

• Request larger than jsonrpc.max-request-bytes returns protocol error payload.

Action:

• Increase limit if use case requires larger requests.
• Consider splitting large payload into smaller calls.

Build Fails with NullAway Error

Symptom:

• ./gradlew check fails with [NullAway] diagnostics.

Cause:

• Production source code violated null-safety contracts enforced at compile time.

Checks:

• Add @Nullable to parameters/returns/fields that can legitimately be null.
• Add explicit null guard and fallback values before passing data into non-null APIs.
• Align overridden method signatures with nullable contracts from super interfaces/classes.
• For JSON-RPC request/response models, keep nullability aligned with protocol semantics.