Debugging & Breakpoints

Learn how to use soli's powerful debugging tools including breakpoints, interactive REPL, and the development error page.

Breakpoints

Use the break() function to pause execution and open the interactive debug page. This is useful for inspecting variable state and understanding program flow.

Setting Breakpoints

fn process_user(user_id: Int) -> Hash {
    let user = database.find(user_id);

    // Set a breakpoint to inspect the user object
    break();

    if (user == null) {
        return {"error": "User not found"};
    }

    let profile = enrich_profile(user);

    // Another breakpoint to see enriched data
    break();

    return profile;
}

Why Use Breakpoints?

Inspect State

Examine variable values and data structures at any point in your code

Trace Execution

Follow the program flow step by step to understand logic

Evaluate Code

Run arbitrary soli code to test hypotheses or calculate values

Debug Errors

Automatically triggered on errors to help diagnose issues

Tip

Breakpoints only work in development mode. In production, break() calls are ignored.

Debug Page

When a breakpoint is hit or an error occurs, soli displays a comprehensive debug page with multiple panels for investigation.

Debug Page Features

// Interactive REPL - Execute soli code in breakpoint context
// Stack Trace - Navigate through call stack frames
// Source Viewer - View source code with line highlighting
// Request Inspector - Examine request params, query, headers, body
// Environment Info - View time, method, path of the request

Stack Trace Navigation

Click on any stack frame to view the source code at that location. The source viewer shows the relevant code with the error line highlighted.

Stack Trace:
  0. process_user at ./src/users.soli:15
  1. handle_request at ./src/routes.soli:42
  2. main at ./src/main.soli:8

Click on any frame to see the source code.

Source Code Viewer

The source viewer displays code around the breakpoint or error location with:

Line numbers for easy reference
Highlighted error/breakpoint line
Context lines above and below
Syntax highlighting

Interactive REPL

The debug page includes an interactive REPL that runs in the context of your breakpoint. You can execute any soli code to inspect and manipulate data.

Available Variables

// Request object - access all request data
req              // Full request object
req["params"]    // Route parameters (e.g., {id: "123"})
req["query"]     // Query string parameters
req["body"]      // Request body (POST/PUT data)
req["headers"]   // HTTP headers

// Session
session          // Session data

// Breakpoint context
breakpoint_env   // Local variables at breakpoint

REPL Features

// Use @ to reference the last result
req["params"]["id"]  // Returns: "123"
@ + 100              // Returns: 223 (uses last result)

// Navigation with arrow keys
// Up/Down: Browse command history

// Execute any valid soli code
print("Debug output");
user["name"];        // Inspect variable
config["database"];  // View configuration

Quick Inspect Buttons

Click the quick inspect buttons to instantly view common data:

// Available quick inspect buttons:
req        // View full request object
params     // View route parameters
query      // View query string
body       // View request body
session    // View session data
headers    // View HTTP headers

Development Mode

Start the development server with hot reload to enable all debugging features:

# Start development server with hot reload
soli serve

# The server will automatically reload when files change
# Breakpoints and debug page work in this mode

Development vs Production

Feature	Development	Production
Breakpoints	Enabled	Disabled
Debug Page	Full interactive	Simple error
Hot Reload	Enabled	Disabled
Stack Traces	Detailed	Minimal

Security Warning

Never run in development mode in production. The debug page exposes sensitive information including request data, environment variables, and source code.

Next Steps

Combine debugging with testing to build robust applications.

Testing Guide Live Reload