Debugging

Frappe provides multiple ways to debug both server-side and client-side code. During development, you can monitor process logs, print debugging information, use the interactive Bench console, inspect JavaScript in the browser, or attach a debugger using Visual Studio Code.

Server-side Debugging

Running the following command starts all required development processes defined in the Bench Procfile.

bench start

Each process writes its output directly to the terminal, making it easy to monitor application activity and identify runtime errors.

Typical Processes Started

• Web server
• Redis Cache
• Redis Queue
• Redis SocketIO
• SocketIO Server
• Scheduler
• Background Workers
• Asset Watcher

If you add print() statements inside your Python code:

• Request-response code appears in the web process.
• Background jobs appear in the appropriate worker_* process.

Application Logs

Frappe automatically stores log files that can be used to troubleshoot issues in development and production environments.

Bench-level logs are generated by supporting services, while site-level logs contain application-specific events and errors.

Bench Console

Bench provides an interactive IPython shell that automatically loads the Frappe framework and connects to the selected site’s database.

bench --site [sitename] console

Example:

In [1]: frappe.get_doc("Task", "TASK00004")

This console is useful for testing APIs, inspecting records, running database queries, and debugging business logic interactively.

Client-side Debugging

JavaScript code can be debugged directly in your browser using Developer Tools.

Simply add a debugger statement where execution should pause.

frappe.db.get_value("Task", "TASK00004", "status")
    .then(values => {
        debugger;
        console.log(values);
    });

When Developer Tools are open, execution pauses at the debugger statement, allowing you to inspect variables, call stacks, and network activity.

Browser Console

The globally available frappe object lets you execute client-side APIs directly from your browser console.

This is useful for testing API calls, inspecting objects, experimenting with client scripts, and verifying JavaScript behavior without modifying application code.

Debugging with Visual Studio Code

VS Code supports debugging Frappe applications using the Python Debug Adapter Protocol (DAP), allowing you to place breakpoints directly inside your Python files.

Setup Checklist

• Modify the Bench Procfile.
• Install Visual Studio Code.
• Install the Python extension.
• Create or update launch.json.
• Run bench start.
• Start the debugger from VS Code.

Step 1: Update Procfile

Comment out the default web server entry so that VS Code can launch it instead.

web: bench serve --port 8000

Step 2: Configure launch.json

Add the following configuration to your VS Code workspace.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Bench",
            "type": "python",
            "request": "launch",
            "justMyCode": false,
            "program": "${workspaceFolder}/frappe/frappe/utils/bench_helper.py",
            "args": [
                "frappe",
                "serve",
                "--port",
                "8000",
                "--noreload",
                "--nothreading"
            ],
            "python": "${workspaceFolder}/../env/bin/python",
            "cwd": "${workspaceFolder}/../sites",
            "env": {
                "DEV_SERVER": "1"
            }
        }
    ]
}

Step 3: Start Bench

bench start

Keep this command running while debugging.

Step 4: Start the Debugger

Open the Run and Debug panel in VS Code and launch the Bench configuration. Your breakpoints will now pause execution inside the application.

Understanding the VS Code Configuration

Debugger Limitations

• Automatic code reloading is disabled while using the VS Code debugger.
• Werkzeug multithreading is disabled during debugging sessions.
• Manual restart or reload may be required after code changes.