Hotjar debug mode can be enabled in your browser to troubleshoot complex issues and confirm that Hotjar is working correctly. This article will explain how to enable debug mode, share some common use cases, and provide information about specific debug log messages.
Keep scrolling, or click ahead to one of the sections below to learn more:
- How to enable debug mode via the URL
- How to enable debug mode with cookies
- Use cases
- Log messages reference guide
How to enable debug mode via the URL
Add the debug parameter to your page URL
Enabling debug mode is done by adding the following URL parameter to the end of the page you're working on: ?hjDebug=1
For example, to debug https://www.hotjar.com/blog/, we would use this URL instead: https://www.hotjar.com/blog/?hjDebug=1
Open your browser Developer Tools
Here are the steps used to open developer tools in the following browsers:
- Chrome - on the menu bar click View > Developer > Developer Tools
- Firefox - on the menu bar click Tools > Browser Tools > Web Developer Tools
- Safari - on the menu bar click Develop > Show JavaScript Console
Reload the page
Reloading the page, after the steps above have been completed, will ensure that you're able to see all the debug logs that occurred during the page load. When the Console logs appear, they'll look similar to these:
*Debug logs are visible in the Console tab of your browser Developer Tools.
How to enable debug mode with cookies
Open your browser Developer Tools
Here are the steps used to open developer tools in the following browsers:
- Chrome - on the menu bar click View > Developer > Developer Tools
- Firefox - on the menu bar click Tools > Browser Tools > Web Developer Tools
- Safari - on the menu bar click Develop > Show JavaScript Console
Open the Application tab
Open your cookies by selecting the Application tab.
Add hjDebug as a Cookie
Scroll to the bottom of the cookies and double click in the empty space. Then type hjDebug in to the Name column.
Set cookie to true
In the second column, type the word true to set the cookie, then hit ENTER.
Reload the page
Reloading the page, after the steps above have been completed, will ensure that you're able to see all the debug logs that occurred during the page load. When the Console logs appear, they'll look similar to these:
Use Cases
Debug mode is frequently used by developers to test Events and Identify API functions. However, they can also be used to see if targeting criteria are being met and to help troubleshoot why a Survey isn't appearing on a page. This section will share some examples of how it works.
Search the Console tab to find relevant debug logs
You can use Ctrl+F (Windows) or command+F (Mac) to search the Console tab for specific messages. The screenshots below show examples of search terms that were used to reduce the number of log entries visible in the browser Console.
Events API
The debug logs will show when a Hotjar Event has been fired successfully in the browser. When an event is fired successfully, a confirmation message will appear in blue similar to the last message in the screenshot below:
COMMAND: Processing command: event testEvent
Where 'testEvent' would represent the unique name of the Event being fired.
In order to trigger this manually, you could enter the following directly into your browser Console:
hj('event', 'testEvent');
Identify API
When an Identify API call is received by Hotjar, a confirmation message will appear in blue, similar to the example image below:
COMMAND: Processing command: identify , {"userAttribute":"value"}
Where "userAttribute" is the name of the attribute received, and "value" is a value associated with that attribute.
You can manually send an API call to Hotjar by entering the following into your browser Console:
hj('identify', null, {
userAttribute: 'value'
});
Additionally, you can see logs that state whether or not attributes have been changed by searching for "attribute" in the Console window. The results will look similar to this:
Surveys
Debug mode can be helpful for understanding the behavior of Survey because it will show when a tool has matched the target criteria as well as when it renders on the page.
For example, searching "poll" in the Console can allow you to find messages related to the Surveys tool. In the example below, we see that a specific survey (ID: 888238) has matched the target criteria on the page, and Hotjar has called the poll (survey) to appear on the page.
Log messages reference guide
Currently, we don't have a comprehensive list of all the possible debug log messages. However, this is something our team will explore in the future and we'll update this doc as more information is made available. If you have any trouble getting Hotjar tools and features to work, please reach out to our support team using the Contact Us button below this article.
Content Security Policy errors
If you notice any errors that mention Hotjar domains (hotjar.com, hotjar.io, etc.) and relate to "Content Security Policy", be sure to check out this article for steps on how to resolve them.
The following table contains some common Hotjar Debug log messages that you might encounter while using Hotjar on your website:
Session capture logs
| Log message | Meaning |
| WEBSOCKET: Connecting to Web Socket [wss://wsp4.hotjar.com/api/v2/client/ws] | Hotjar is attempting to open a Web Socket on the page. |
| WEBSOCKET: Web Socket opened. | Confirmation that the Web Socket opened successfully. |
| WEBSOCKET: Sending data to Web Socket: | Confirmation that the Web Socket is receiving data from the page. This is required for session data to be captured by Recordings and Heatmaps. |
User Attributes and Event logs
| Log message | Meaning |
| COMMAND: Processing command: identify , {"userAttribute":"value"} | An Identify API call was detected. In the example message to the left, a user attribute called userAttribute was sent with a value of value. |
| USERATTRIBUTES: No recording in progress. Not sending. | An Identify API call was detected, but the user's session is not being tracked by Hotjar. This can happen when your site is experiencing Sampling. |
| COMMAND: Command "identify" blocked due to opt-out | This message is usually related to the Do Not Track (DNT) settings of the browser. If DNT is enabled, Hotjar will discard all User Attributes for the session. |
| USERATTRIBUTES: User attributes sent up websocket.: (Expand for attributes) | User Attributes are detected and being sent to Hotjar servers. |
| USERATTRIBUTES: User Attributes validation API call failed.: | The call to the Identify API failed, expand the message to see the reason. For example: "User has no user_id or attributes." |
| COMMAND: Processing command: event action_name | A Hotjar Event fired on the page. In the example message to the left, the event name was action_name. |
Surveys logs
| Log message | Meaning |
| POLL: Poll #xxxxxx has matched. | A survey on the page has matched the targeting criteria. The #xxxxxx number refers to the survey ID within Hotjar. Multiple tools could be matching on the same page. |
| RENDERING: Calling active item (poll): x | Hotjar is initiating a matching survey to appear on the page. The value of x will be immediate, delay, abandon, or scroll depending on the behavior configurations of the survey. |
| POLL: Rendering poll widget. | The survey should now be visible on the live page. |
| POLL: Poll was already submitted. | The survey matched the targeting criteria, but is configured to no longer appear after the user has already responded. |