Troubleshooting JSS Next.js apps

If you encounter unexpected JavaScript errors during the npm install or build steps, especially errors that other team members cannot reproduce, check the versions of Node and npm being used. From a terminal, run:

node -v
npm -v

We test JSS using the Long Term Support (LTS) versions of Node. These are typically one major version behind the latest official Node version.

The Node/npm version used by your CI/Production environments may differ from the version your local environment uses. When a project configuration does not require a specific Node/npm version in package.json, deployment agents commonly build using the most recent version available or an environment-specific "default" version.

If you need to swap between multiple Node versions on your local environment for testing, you can use third-party packages like n or nvm.

If you are working with a local Sitecore instance using a privately signed certificate, you might experience the following error:

To resolve this error, configure Sitecore CA certificates for Node.js.

If the import role does not have the correct permissions, you might experience the following error:

IMPORT ERROR(S) OCCURRED!
Exception thrown while importing JSS app
Exception: Sitecore.Exceptions.AccessDeniedException
Message: AddFromTemplate - Add access required

Refer to Errors when importing JSS application on Azure for the solution.

Building and rendering a JSS Next.js app depend on successfully fetching data using GraphQL. The most common cause of failed builds and apps that cannot render pages is an issue with the data-fetching process.

The GraphiQL interface at <sitecore hostname + graphQL endpoint>/ui?sc_apikey=<api key> is a visual browser for GraphQL data. It is a useful tool for diagnosing these types of issues.

To support static generation functionality, the sample app uses a GraphQL query to retrieve Sitecore paths. Try running this query directly in GraphiQL.

# YOUR_PATH should be the ID of your site root (home page) in lower-case, with dashes removed.
# YOUR_LANGUAGE should be your default language, as defined in package.json

query{
  search(where: {
    AND:[
      {
      name:"_path",
      value:"YOUR_PATH"
      },
      {
      name:"_language",
      value:"YOUR_LANGUAGE"
      },
      {
      name:"_hasLayout",
      value :"true"
      }
    ]
  })
  { 
    total
    results {
        url {
          path
        }
      }
  }"
}

If you do not see the expected results, try the following steps:

You might encounter this problem when the application cannot restore the data in localStorage. For example, if you tried to open a URL with an embedded query and the query was invalid.

To solve the problem:

This error occurs when loading GraphiQL in the same browser where you logged in to Sitecore.

To solve the issue, append sc_mode=normal to the URL query parameters.

After creating a new user in the Sitecore Editor Role, attempting to edit the JSS app items in Sitecore might warn that the user does not have read access rights.

The workaround is to set Workflow State Write for the System/Workflows/JSS development workflow item manually, enabling the Published state, which is final, to be editable. It allows the user to create a new version of an item for editing using the Lock and Edit option.

When opening a JSS app configured to use the HTTP rendering engine (such as a Next.js app) for the first time using the Experience Editor, you might get a timeout error from the rendering host with the message The operation has timed out. In the logs, you can might see the following:

10292 10:51:16 ERROR [JSS] Error occurred during POST to remote rendering host: `http://localhost:3000/api/editing/render`
10292 10:51:16 ERROR The operation has timed out
Exception: System.Net.WebException
Message: The operation has timed out
Source: System
at System.Net.WebClient.UploadDataInternal(Uri address, String method, Byte[] data, WebRequest& request)
at System.Net.WebClient.UploadString(Uri address, String method, String data)
at Sitecore.JavaScriptServices.ViewEngine.Http.RenderEngine.Invoke[T](String moduleName, String functionName, Object[] functionArgs)

To resolve the issue, edit the \App_Config\Sitecore\JavaScriptServices\Sitecore.JavaScriptServices.ViewEngine.Http.config file to increase the value of the RequestTimeoutMs setting. For example:

<!-- Specifies the maximum duration, in milliseconds, that your .NET code should wait for requests to the HTTP renderer (e.g. the `EndpointUrl` setting) to respond. -->
<RequestTimeoutMs>10000</RequestTimeoutMs>

If you have an SXA integration with a JSS tenant and you deploy Next.js items into the JSS tenant, you might encounter a GraphQL query error when trying to start the Next.js app in production mode:

Error: Valid value for rootItemId not provided and failed to auto-resolve app root item.

This error occurs because the Next.js app and Next.js app items deployed into JSS tenant reference different templates, causing the query to fail.

To prevent the error, define a rootItemId for your instances of GraphQL services as follows:

If the GraphQL schema changes, you must regenerate GraphQL introspection data.

In the sample app, you regenerate introspection data using the command jss graphql:update.

If your app renders and builds correctly in your local development environment, but fails to render when deployed to Vercel, a possible reason for the issue might be an incorrect upgrade to version 18.0.0 or later.

When creating your Next.js application using the jss create command, based on the options you chose or the default values for --fetchWith and --prerender options, the script cleans up after itself.

When upgrading your Next.js application from JSS 16.0 to JSS 18.0, manually and copying the latest code from the repository, this automatic cleanup does not happen. Prior to version 18.0, [[...path]].SSR.tsx was located at src/pages_examples/. In version 18.0.0 and later, because of improvements to the jss create command, the source for the Next.js sample application holds both catch-all dynamic routes for the [...path] parameter in src/pages.

To resolve the rendering issue:

Typing in an empty text field creates the following error message:

Uncaught TypeError: Cannot read property 'baseNode' of undefined

This is a known issue in the Experience Editor, and we expect to fix it in a future release. It does not affect the functionality, and you can safely ignore it.

When you run Next.js in development mode, Next.js displays runtime errors in an overlay.

This issue does not occur when Next.js runs in production mode and does not affect Content Authors.