Appendix: Debugging Guide

Troubleshooting and Diagnostic Techniques

← Back to Building and Integrating Custom RPC Handlers

Introduction

Even with careful coding, issues will arise during RPC handler development. This guide provides systematic approaches to diagnosing and fixing problems, from compilation errors to runtime issues to performance bottlenecks.

The key is having the right tools and techniques to isolate the problem quickly.

Common Compilation Errors

Error 1: Undeclared Identifiers

Error Message:

error: 'jss::my_field' was not declared in this scope

Root Causes:

Typo in JSON string constant name
Using string literal instead of jss:: constant
Missing include file

Solution:

// WRONG - String literal
result["my_field"] = value;

// CORRECT - Use jss:: constant
result[jss::my_field] = value;

// If jss::my_field doesn't exist, add to jss.h or define:
namespace ripple { namespace jss {
    constexpr auto my_field = "myField";
}} // ripple::jss

Prevention:

Always use jss:: constants from xrpl/protocol/jss.h
Check spelling carefully
Refer to existing handlers for correct constant names

Error 2: Type Mismatch in RPC Functions

Error Message:

error: no matching function for call to 'rpcError'

Root Causes:

Wrong parameter types
Missing required parameters
Template specialization issues

Solution:

// WRONG - Wrong return type
result[jss::error] = rpcError(rpcINVALID_PARAMS);  // This is Json::Value, not bool

// CORRECT - Return directly
return rpcError(rpcINVALID_PARAMS);

// WRONG - Missing error code
return rpcError("Missing account");

// CORRECT - Include error code
return rpcError(rpcINVALID_PARAMS, "Missing account");

Error 3: Const Correctness Issues

Error Message:

error: invalid conversion from 'const ripple::AccountID*' to 'ripple::AccountID*'

Root Causes:

Discarding const qualifier
Passing const reference where non-const expected
Missing const in function signature

Solution:

// WRONG - Losing const
auto const account = *accountOpt;
// account is const AccountID, can't be modified
auto nonConst = const_cast<AccountID*>(&account);  // DON'T DO THIS

// CORRECT - Keep const where needed
auto const account = *accountOpt;
auto const sle = ledger->read(keylet::account(account));

// WRONG - Function signature drops const
void processAccount(AccountID& account);

// CORRECT - Mark as const
void processAccount(AccountID const& account);

Error 4: Missing Include Files

Error Message:

error: 'parseBase58' was not declared in this scope
error: 'RPC::lookupLedger' was not declared in this scope

Solution:

// Add required includes at top of handler file:
#include <xrpld/app/main/Application.h>
#include <xrpld/rpc/Context.h>
#include <xrpld/rpc/detail/RPCHelpers.h>
#include <xrpl/protocol/ErrorCodes.h>
#include <xrpl/protocol/jss.h>
#include <xrpl/basics/base_uint.h>
#include <xrpl/basics/Blob.h>

Checklist:

RPCHelpers.h for helper functions
Context.h for RPC::JsonContext
ErrorCodes.h for error constants
jss.h for JSON string constants
base_uint.h for uint256 and similar
AccountID.h if using AccountID directly

Runtime Debugging Techniques

Technique 1: Strategic Logging

Adding Debug Output:

#include <xrpld/core/XRPLedger.h>  // For JLOG

Json::Value doMyHandler(RPC::JsonContext& context)
{
    JLOG(context.app.journal("RPC").debug())
        << "doMyHandler called with params: "
        << context.params.toStyledString();

    if (!context.params.isMember(jss::account)) {
        JLOG(context.app.journal("RPC").warning())
            << "Missing account parameter";
        return rpcError(rpcINVALID_PARAMS);
    }

    auto const account = parseBase58<AccountID>(
        context.params[jss::account].asString());

    if (!account) {
        JLOG(context.app.journal("RPC").warning())
            << "Failed to parse account: "
            << context.params[jss::account].asString();
        return rpcError(rpcACT_MALFORMED);
    }

    JLOG(context.app.journal("RPC").debug())
        << "Successfully parsed account: " << to_string(*account);

    return buildResponse(*account, ledger);
}

Journal Levels:

fatal() - Application stopping
error() - Significant problems
warning() - Unexpected but recoverable
info() - General informational
debug() - Detailed diagnostic (hidden in release builds)
trace() - Very detailed (rarely used)

Viewing Output:

# Build with debug logging enabled
./rippled -a --log-level rpc=debug

# Output typically goes to console or rippled.log
tail -f rippled.log | grep "RPC"

Technique 2: Using the Debugger (GDB)

Building for Debugging:

cd rippled
git submodule update --init --recursive
mkdir -p build
cd build

# Build with debug symbols
cmake -DCMAKE_BUILD_TYPE=Debug \
      -DCMAKE_CXX_COMPILER=clang++ \
      ..

make rippled

Launching Debugger:

# Start rippled under GDB with minimal ledger
cd build
gdb --args ./rippled --standalone

# Or attach to running process
gdb attach <process_id>

GDB Commands:

# Set breakpoint in handler
(gdb) break src/xrpld/rpc/handlers/MyHandler.cpp:45

# Set conditional breakpoint
(gdb) break MyHandler.cpp:45 if account_id == 0x1234

# Run until breakpoint
(gdb) run

# Step into function
(gdb) step

# Step over function
(gdb) next

# Continue execution
(gdb) continue

# Print variable
(gdb) print account
(gdb) print *account
(gdb) print account->field

# Print with pretty formatting
(gdb) set print pretty on

# Examine memory
(gdb) x/32bx account  # 32 bytes in hex format

# Get stack trace
(gdb) backtrace

Common GDB Debugging Pattern:

# 1. Set breakpoint at handler entry
(gdb) break doMyHandler

# 2. Run and hit breakpoint
(gdb) run
Breakpoint 1, doMyHandler (context=0x7fff...) at MyHandler.cpp:25

# 3. Print context details
(gdb) print context.params
(gdb) print context.role

# 4. Step through code
(gdb) next
(gdb) print account

# 5. If crash, examine state
(gdb) backtrace
(gdb) frame 0
(gdb) print *ledger

Technique 3: Using LLDB (macOS)

Similar to GDB but with slightly different syntax:

# Build for debug (same as GDB)
cmake -DCMAKE_BUILD_TYPE=Debug ...

# Start LLDB
lldb -- ./rippled --standalone

LLDB Commands:

# Set breakpoint
(lldb) breakpoint set --file MyHandler.cpp --line 45

# More concise
(lldb) br set -f MyHandler.cpp -l 45

# Run
(lldb) run

# Step/next/continue (same as GDB)
(lldb) step
(lldb) next
(lldb) continue

# Print variable
(lldb) frame variable account
(lldb) p context.params

# Backtrace
(lldb) bt

Technique 4: Analyzing Crashes

When handler crashes (segmentation fault):

# 1. Get core dump
ulimit -c unlimited

# 2. Run rippled
./rippled --standalone

# 3. When it crashes, analyze core dump
lldb ./rippled -c /cores/core.12345

# 4. In debugger
(lldb) bt                    # See where crash happened
(lldb) frame variable        # Print local variables
(lldb) p pointer_variable    # Check for null pointers

Common Crash Scenarios:

// CRASH 1: Null pointer dereference
auto const sle = ledger->read(keylet);
if (!sle) {
    auto value = sle->getFieldU32(sfBalance);  // CRASH! sle is null
}

// FIX: Check before use
auto const sle = ledger->read(keylet);
if (!sle) {
    return rpcError(rpcACT_NOT_FOUND);
}
auto value = sle->getFieldU32(sfBalance);  // Safe


// CRASH 2: Dereferencing invalid optional
auto const accountOpt = parseBase58<AccountID>(str);
auto const sle = ledger->read(keylet::account(*accountOpt));  // CRASH if empty

// FIX: Validate before deref
auto const accountOpt = parseBase58<AccountID>(str);
if (!accountOpt) {
    return rpcError(rpcACT_MALFORMED);
}
auto const sle = ledger->read(keylet::account(*accountOpt));  // Safe

Log Level Configuration

Setting Log Levels

In Config File (rippled.cfg):

[rpc]
port = 5005
ip = 127.0.0.1

[logging]
# General log level
log_level = info

# Specific module levels
rpc = debug
ledger = warning
transaction = info

Command Line:

./rippled --log-level rpc=debug --log-level ledger=trace

./rippled -a --log-level rpc=debug  # -a for standalone mode

Common Modules to Debug:

rpc - RPC handler execution
ledger - Ledger operations
transaction - Transaction processing
app - Application lifecycle
protocol - Protocol messages
peer - Network peer communication

Interpreting Log Output

Typical Log Format:

[2024-11-16T10:30:45.123Z] RPC {getAccountInfo:3} Running handler: account_info
[2024-11-16T10:30:45.125Z] RPC {getAccountInfo:3} Query result: success
[2024-11-16T10:30:45.126Z] RPC {getAccountInfo:3} Returning: {"account":"rN7n7...","balance":"1000000"}

Log Levels Mean:

[FATAL] - Rippled about to stop
[ERROR] - Handler failed, returned error
[WARN] - Unusual condition, but handler succeeded
[INFO] - Normal informational messages
[DEBUG] - Detailed execution trace (very verbose)
[TRACE] - Extremely detailed (rarely used)

Testing Strategies

Strategy 1: Unit Testing Handlers

Test File Structure (src/test/rpc/handlers/MyHandler_test.cpp):

#include <gtest/gtest.h>
#include <xrpld/rpc/handlers/MyHandler.h>
#include <test/jtx.h>

namespace ripple::test {

class MyHandlerTest : public testing::Test {
protected:
    void SetUp() override {
        // Initialize test fixtures
    }
};

TEST_F(MyHandlerTest, ValidRequest) {
    // Arrange
    Json::Value params;
    params[jss::account] = "rN7n7otQDd6FczFgLdlqtyMVrnPQGEDE8";

    // Act
    auto result = doMyHandler(context);

    // Assert
    ASSERT_FALSE(result.isMember(jss::error));
    ASSERT_TRUE(result.isMember(jss::result));
}

TEST_F(MyHandlerTest, MissingAccountParam) {
    // Arrange
    Json::Value params;  // Empty params

    // Act
    auto result = doMyHandler(context);

    // Assert
    ASSERT_TRUE(result.isMember(jss::error));
    ASSERT_EQ(result[jss::error_code].asInt(), rpcINVALID_PARAMS);
}

TEST_F(MyHandlerTest, MalformedAccount) {
    // Arrange
    Json::Value params;
    params[jss::account] = "invalid-address";

    // Act
    auto result = doMyHandler(context);

    // Assert
    ASSERT_EQ(result[jss::error_code].asInt(), rpcACT_MALFORMED);
}

}  // namespace ripple::test

Running Tests:

cd build
cmake -DBUILD_TESTS=ON ..
make

# Run all tests
./rippled-tests

# Run specific test suite
./rippled-tests --gtest_filter="MyHandlerTest.*"

# Run with verbose output
./rippled-tests --gtest_filter="MyHandlerTest.*" -v

Strategy 2: Integration Testing

Testing with Live Ledger:

# Terminal 1: Start rippled in test mode
./rippled --standalone --start --log-level rpc=debug

# Terminal 2: Send test requests
curl -s -X POST \
  http://localhost:5005 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "account_info",
    "params": {
      "account": "rN7n7otQDd6FczFgLdlqtyMVrnPQGEDE8"
    }
  }' | jq .

# Watch logs in Terminal 1
tail -f rippled.log | grep RPC

Strategy 3: Performance Testing

Measuring Handler Execution Time:

#include <chrono>

Json::Value doMyHandler(RPC::JsonContext& context)
{
    auto start = std::chrono::high_resolution_clock::now();

    // Handler implementation
    Json::Value result = buildResponse(context);

    auto end = std::chrono::high_resolution_clock::now();
    auto duration = std::chrono::duration_cast<std::chrono::milliseconds>(
        end - start);

    JLOG(context.app.journal("RPC").debug())
        << "Handler execution: " << duration.count() << "ms";

    return result;
}

Performance Troubleshooting

Issue: Handler is Slow

Diagnostic Steps:

Add timing logs:

JLOG(journal.debug()) << "Starting parameter parsing";
// parse parameters
JLOG(journal.debug()) << "Parameter parsing complete";

JLOG(journal.debug()) << "Starting ledger lookup";
// lookup ledger
JLOG(journal.debug()) << "Ledger lookup complete";

JLOG(journal.debug()) << "Starting ledger queries";
// query ledger
JLOG(journal.debug()) << "Ledger queries complete";

Identify bottleneck:

# From logs, which step takes longest?
tail -f rippled.log | grep MyHandler

Optimize identified bottleneck:
- Cache frequently accessed values
- Minimize ledger reads
- Use indexed lookups when available
- Avoid redundant computations

Issue: High Memory Usage

Diagnostic:

// Are you creating large intermediate objects?
std::vector<SLE> allAccounts;  // AVOID for large sets

// Better: Stream or use iterators
for (auto const& account : accounts) {
    // Process one at a time
}

// Are you keeping references alive?
auto const& ref = expense_object;  // Keeps reference
// ... lots of code ...
// Reference still alive, can't be freed

Checklist: Debug Workflow

When your handler isn't working:

Compile errors?
- Check includes
- Verify jss:: constants exist
- Check type mismatches
- See "Common Compilation Errors" section
Crashes immediately?
- Use debugger to get stack trace
- Check for null pointer dereferences
- Verify optional types before use
Returns wrong result?
- Add logging to see parameter values
- Verify ledger lookup succeeded
- Check JSON response structure
- Print intermediate values
Slow execution?
- Add timing logs around sections
- Identify slowest section
- Minimize ledger operations
- Cache repeated queries
Inconsistent behavior?
- Check error handling paths
- Verify state assumptions
- Test with different inputs
- Check for race conditions (multi-threaded)

Resources

Debugging Tools:

GDB: https://sourceware.org/gdb/
LLDB: https://lldb.llvm.org/
Valgrind: https://valgrind.org/ (memory debugging)

Rippled Specific:

Source: https://github.com/XRPLF/rippled
Build docs: Rippled documentation
Community: XRPL Discord #coredev channel

← Back to Appendices | Helper Functions

Related Module Sections:

PreviousAppendix: Helper Functions NextHomeworks

Last updated 1 month ago

hashtagTroubleshooting and Diagnostic Techniques

hashtagIntroduction

hashtagCommon Compilation Errors

hashtagError 1: Undeclared Identifiers

hashtagError 2: Type Mismatch in RPC Functions

hashtagError 3: Const Correctness Issues

hashtagError 4: Missing Include Files

hashtagRuntime Debugging Techniques

hashtagTechnique 1: Strategic Logging

hashtagTechnique 2: Using the Debugger (GDB)

hashtagTechnique 3: Using LLDB (macOS)

hashtagTechnique 4: Analyzing Crashes

hashtagLog Level Configuration

hashtagSetting Log Levels

hashtagInterpreting Log Output

hashtagTesting Strategies

hashtagStrategy 1: Unit Testing Handlers

hashtagStrategy 2: Integration Testing

hashtagStrategy 3: Performance Testing

hashtagPerformance Troubleshooting

hashtagIssue: Handler is Slow

hashtagIssue: High Memory Usage

hashtagChecklist: Debug Workflow

hashtagResources

hashtagNavigation

Troubleshooting and Diagnostic Techniques

Introduction

Common Compilation Errors

Error 1: Undeclared Identifiers

Error 2: Type Mismatch in RPC Functions

Error 3: Const Correctness Issues

Error 4: Missing Include Files

Runtime Debugging Techniques

Technique 1: Strategic Logging

Technique 2: Using the Debugger (GDB)

Technique 3: Using LLDB (macOS)

Technique 4: Analyzing Crashes

Log Level Configuration

Setting Log Levels

Interpreting Log Output

Testing Strategies

Strategy 1: Unit Testing Handlers

Strategy 2: Integration Testing

Strategy 3: Performance Testing

Performance Troubleshooting

Issue: Handler is Slow

Issue: High Memory Usage

Checklist: Debug Workflow

Resources

Navigation