Debugging APEX Like a Pro: APEX_DEBUG and the Debug Toolbar

When Something Goes Wrong

Debugging APEX applications is fundamentally different from debugging traditional desktop applications. There is no step through debugger, no breakpoints, and the application spans server side PL/SQL and client side JavaScript. Mastering APEX’s built in debugging tools is essential for efficient troubleshooting.

Enabling Debug Mode

The quickest way to enable debug mode is to click the “Debug” button in the APEX Developer Toolbar at the bottom of the page. This adds &debug=YES to the URL and tells APEX to log detailed information about every step of page rendering and processing. After reproducing the issue, click “View Debug” to see the log.

APEX supports multiple debug levels, from Level 1 (errors only) through Level 9 (maximum verbosity). For most debugging, Level 4 or Level 6 provides enough detail without overwhelming you:

-- In the URL
&debug=LEVEL6

-- Or programmatically
APEX_DEBUG.ENABLE(p_level => 6);

Adding Custom Debug Messages

The APEX_DEBUG package lets you add your own messages to the debug log, which appear alongside APEX’s internal messages in chronological order. This is invaluable for tracing the flow through your custom PL/SQL processes:

BEGIN
    APEX_DEBUG.MESSAGE('Starting order processing for PO: %s', :P50_PO_NUMBER);

    -- Your logic here
    APEX_DEBUG.MESSAGE('Calculated total: %s for %s line items',
                       l_total, l_line_count);

    IF l_total > l_approval_threshold THEN
        APEX_DEBUG.WARN('Total %s exceeds approval threshold %s',
                        l_total, l_approval_threshold);
    END IF;

EXCEPTION
    WHEN OTHERS THEN
        APEX_DEBUG.ERROR('Order processing failed: %s', SQLERRM);
        RAISE;
END;

The Debug Log Viewer

Access the debug log viewer from the APEX developer toolbar or from App Builder under Utilities then Debug Messages. The viewer shows each execution step with its elapsed time, which is crucial for identifying performance bottlenecks. Look for steps with unusually high elapsed times, they point directly to slow queries or expensive computations.

Client Side Debugging

For Dynamic Action and JavaScript issues, use the browser’s Developer Tools console. APEX logs Dynamic Action execution to the console when debug mode is active. You can also add console.log() statements to your custom JavaScript. For AJAX callback debugging, the Network tab in Developer Tools shows every request and response, including the data sent to and returned from the server.

A Systematic Approach

When debugging, work methodically. Enable debug mode. Reproduce the issue. Check the debug log for errors or unexpected flow. Check the browser console for JavaScript errors. Check the Network tab for failed AJAX calls. Each of these tools covers a different layer of the application stack, and the bug will be visible in at least one of them.