Reading time: 5 min read
The Ultimate Guide of Sitecore JSS Debug Logs
Everything you ever wanted to know about Sitecore JSS debug logging, and even more!
What is Debug Logging in Sitecore JSS?
Did you know that the Sitecore JSS SDK has built-in debug logging that uses the debug NPM package for logging additional information during its functions execution? Let’s explore its features and how to set it up.
Available Namespaces
Sitecore split debug logs by namespace under the root namespace sitecore-jss for ease of use when troubleshooting a specific issue:
- sitecore-jss:http
- sitecore-jss:dictionary
- sitecore-jss:layout
- sitecore-jss:editing
- sitecore-jss:personalize
- sitecore-jss:sitemap
- sitecore-jss:robots
- sitecore-jss:redirects
- sitecore-jss:errorpages
- sitecore-jss:multisite
- sitecore-jss:common
You can find the most current list of namespaces along with their description in the official Sitecore documentation.
Enabling Debug Logs by Defining the DEBUG Environment Variable
To enable debug logs, you must define the DEBUG environment variable in your front-end application.
To enable logs for all namespaces, use star:
DEBUG=sitecore-jss:*
To enable logs for a single namespace, specify the namespace name:
DEBUG=sitecore-jss:common
To enable logs for multiple namespaces, separate them by a comma:
DEBUG=sitecore-jss:common,sitecore-jss:sitemap
To enable logs for all namespaces but one, exclude the namespace with a minus sign:
DEBUG=sitecore-jss:*,-sitecore-jss:sitemap
To enable logs for all namespaces but some, exclude the namespaces with minus signs:
DEBUG=sitecore-jss:*,-sitecore-jss:sitemap,-sitecore-jss:robots
Where to Set the DEBUG Environment Variable and See the Logs?
The location of the DEBUG environment variable varies depending on where and how the front-end application is run:
- Local front-end
- Running in a Docker rendering container
- Or connected to a Sitecore XM Cloud environment
- Sitecore XM Cloud editing rendering host
- Public rendering host
For a Local Front-End Running in a Docker Rendering Container or Connected to a Sitecore XM Cloud Environment
When working on a local front-end, you must define the environment variable in your front-end .env or .env.local file. E.g.: headapps\nextjs-starter\.env (previously src\sxastarter\.env). The .env file already has a commented section with examples that you can comment out:
# Sitecore JSS npm packages utilize the debug module for debug logging.
# https://www.npmjs.com/package/debug
# Set the DEBUG environment variable to 'sitecore-jss:*' to see all logs:
#DEBUG=sitecore-jss:*
# Or be selective and show for example only layout service logs:
#DEBUG=sitecore-jss:layout
# Or everything BUT layout service logs:
#DEBUG=sitecore-jss:*,-sitecore-jss:layout
After setting the variable, Next.js should reload the .env file automatically. You might still have to restart your front-end for the change to be effective:
- When running in a Docker rendering container, restart that single container.
- When connected to an XM Cloud environment, restart the next.js development server in your terminal.
To see the logs:
- When running in a Docker rendering container, click the rendering container in Docker Desktop and navigate to the “Logs” tab.
- When connected to an XM Cloud environment, the logs are inline in the terminal window where you started the front-end development server.
For a Sitecore XM Cloud Editing Rendering Host
If you commit a DEBUG environment variable in your front-end .env file, it will be used by Sitecore XM Cloud.
If you did not commit the environment variable or you want to change its value for the XM Cloud editing rendering host, you must define the environment variable in your XM Cloud environment variables. New and modified environment variables are not effective until the re-deployment of your environment.
- Go to XM Cloud Deploy App
- Navigate to the desired project
- Navigate to the desired environment
- Select the “Variables” tab
- Click the “Create variable” button
-
In the dialog, set these values:
- Name: DEBUG
- Value: The namespaces you want to enable debug logs for
- Target: Rendering host
-
Rendering host name: Your rendering host name as defined in your
xmcloud.build.jsonfile
-
In the top-right corner, click the “Options” drop down and select “Build and deploy”
You can see the logs in XM Cloud Deploy App:
- Go to XM Cloud Deploy App
- Navigate to the same project
- Navigate to the same environment
- Select the “Logs” tab
- Expand the “RenderingHost” accordion
- Click the latest log file
If there are no debug logs, it could be because the editing rendering host did not serve any page yet. Try loading a page in the XM Cloud Pages builder for that environment and rendering host.
For a Public Rendering Host
Whether your public rendering host is on Vercel, Netlify, or hosted elsewhere, if you commit a DEBUG environment variable in your front-end .env file, it will be used by the hosting platform.
If you did not commit the environment variable or you want to change its value for your public rendering hosts, you must define the environment variable on that hosting platform. New and modified environment variables are not effective until the re-deployment of your application.
On Netlify, you will see the logs in both these locations:
- Logs > Functions > Next.js Server Handler
- For regular server-side logs
- Logs > Edge Functions
- For
/apiroutes calls
- For
On Vercel, you will see all logs in the project “Logs” tab.
Debug Logs Format
When enabled, the debug logs format is:
DateTime sitecore-jss:namespace message
Example:
2025-01-30T11:10:29.793Z sitecore-jss:common page-props-factory start
2025-01-30T11:10:29.794Z sitecore-jss:layout fetching layout data for /about-us
2025-01-30T11:10:29.794Z sitecore-jss:layout request: { url: 'https://edge-platform.sitecorecloud.io/v1/content/api/graphql/v1?sitecoreContextId=REDACTED', headers: {}, query: 'query {\n' + ' layout(site:"www", routePath:"/about-us", language:"en"){\n' + ' item {\n' + ' rendered\n' + ' }\n' + ' }\n' + ' }', variables: undefined }
2025-01-30T11:10:29.884Z sitecore-jss:layout response in 73ms: { layout: { item: { rendered: [Object] } } }
2025-01-30T11:10:29.957Z sitecore-jss:common page-props-factory end in 164ms
Troubleshoot on Your Own with JSS Debug Logs
I hope this article provided a good overview of debug logging and detailed all the steps required to enable it in your applications, wherever you host them.
Happy Sitecoring!