The Ultimate Guide of Sitecore JSS Debug Logs

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.

1. Go to XM Cloud Deploy App
2. Navigate to the desired project
3. Navigate to the desired environment
4. Select the “Variables” tab
5. Click the “Create variable” button

6. 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.json file

     

7. 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:

1. Go to XM Cloud Deploy App
2. Navigate to the same project
3. Navigate to the same environment
4. Select the “Logs” tab
5. Expand the “RenderingHost” accordion
6. 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 /api routes calls

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!