Widget troubleshooting guide

reference australia Updated Sep 10, 2026 4 min read widget-troubleshooting-guide.md
Raw file servicenow.com

Use the following tools to investigate and resolve unexpected behavior in your custom Service Portal widgets.

  • Reduce complexity

    Deactivate widgets unrelated to the widget you are troubleshooting to isolate parts of the page that may be causing errors or unexpected behavior. Set the active field to false on a widget record to hide the widget on the page, and prevent associated scripts from executing.

  • Use the browser developer console

    All supported desktop browsers have built in developer tools. Access your browsers developer tools to view console messages and errors thrown by client-side JavaScript. Many of the logging tools detailed below output information to this console.

    If you experience performance issues, check the JavaScript console to see if there are errors, a large number of HTTP requests, or HTTP requests that take a long time to resolve. You can use the console to identify any widgets that load slowly. For more information, see the How to identify a slow widget on a page [KB0744521] article in the Now Support Knowledge Base.

  • Determine the cause of performance issues

    The following tips can help determine the cause of performance issues in portals:

    • Determine if the issue is related to the portal or platform-wide by comparing the functionality in both interfaces. For more information about platform performance issues, see Platform performance.
    • Determine if the issue affects the entire portal or specific pages. If all pages in the portal are slow, check if scripted menu items in the header menu or themes with large font or image files could be the cause. If a specific page is slow, use the browser developer console to determine which widget could be the cause.
    • Check the Log [syslog] table for warnings related to large JSON objects causing slowness. If these warnings are appear with the action that causes slowness, this indicates that a widget is using too much data. For more information, see the Six common performance pitfalls in Service Portal and how to avoid them [KB0634588] article in the Now Support Knowledge Base.

  • Use the widget context menu to access information and options

    CTRL+right-click a widget to access configuration options for the widget. There are also options to output the scope and scope data object to the browser console. For more detail on this menu, see Using portal widgets.

  • Use script methods to capture debugging output

    Several methods are available to output debugging information within your server and client-side code.

Method

Availability

Description

console.log()

Server and client

Logs output to the browser developer console.

$sp.log()

Server

Logs output to the Service Portal Log Entries [sp_log] table, when the logged in user has the sp_admin or admin role.

gs.log()

Server

Logs output to the Log [syslog] table.Note: gs.log creates records on the syslog table. Excessive use can adversely affect performance.

gs.warn()

Server

Produces warning level output in the Log [syslog] table.

gs.error()

Server

Produces error level output in the Log [syslog] table.

gs.addInfoMessage()

Server

Displays a green information message at the top of the browser window.

gs.addErrorMessage()

Server

Displays a red error message at the top of the browser window.

spUtil.addErrorMessage()

Client

Displays an error message within the browser window.

spUtil.addInfoMessage()

Client

Displays an Info message within the browser window.

spUtil.addTrivialMessage()

Client

Displays a message which automatically disappears after a short time.

debugger

Client

Sets a break point in Chrome and Firefox browsers, allowing you to step through a script line by line in the browsers developer console.

{{data|json}}

HTML

This code can be added to the HTML code of a page to output the data object to the portal page in JSON format.
- **Check for security restrictions** 
Often, widget display issues are caused by access rules or user criteria rather than the widget script. Check the user criteria for records and verify that any records that are not accessible within a widget are accessible using the platform UI. Use the ACL debugger to ensure that your users have the expected access to records used by your widgets. For more detail on the debugger, see [ACL debugging tools](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/c_AccessControlRulesDebug.md).

Service Catalog items can also be restricted to not appear in Service Portal. If you get a `You are either not authorized or record is not valid` error message for a Service Catalog widget, check that the item is not hidden from Service Portal.

  • Check the associated Angular Providers

    Verify that the necessary Angular Providers are associated with widgets. Removing the default Angular Providers associated with a base system widget can cause unexpected behavior. For example, removing the scToggleData or scBindHtmlCompile Angular Providers from the SC Catalog Item widget.

  • Create a reference to the widgets scope in the console

    Use reference to a widget to manipulate scope data or manually run the widgets client and server scripts. Use the following steps to create the reference.

      1. Right-click the widget and choose Inspect.
      1. In dev tools Elements tab, click to highlight the element with attribute widget=widget. You can find it a few elements above the currently inspected element. This element points the $0 scripting tool at the widget.

    • In the Javascript console, run the following code:

      JavaScript
      var scopeRef = angular.element($0).scope();

    Use the reference to your widget to change data within the console. See the following example. Remember to run AngularJS $apply() on the scope to apply changes to the page.

    JavaScript
    scopeRef.data.prop1 = "Pear";scopeRef.$apply();

    Run any function defined in the widgets client controller from your reference using the syntax below.

    JavaScript
    scopeRef.exampleFunction();

    Use the refresh command to manually execute the widgets server script.

    JavaScript
    scopeRef.server.refresh();

Parent Topic:Developing custom widgets

Search documentation
Search document titles and file paths on the australia branch