---
title: "Troubleshooting JSS Next.js apps"
slug: "troubleshooting-jss-next-js-apps"
abstract: "How to avoid errors and some workarounds"
---
# Troubleshooting JSS Next.js apps

To help you debug your JSS application, we recommend you [use the debug logging utilities provided by JSS](https://doc.sitecore.com/xp/en/developers/hd/19/sitecore-headless-development/debug-logging-in-jss-apps.html "Debug logging in JSS apps").

You can prevent most errors by performing the following steps:

- Verify that all environment variables used by the app have values. The sample app searches for environment variables in the following order:
    1. `scjssconfig.json`.
    2. `.env`.
    3. `.env.local` (for local environments only).
- If multiple files contain a definition of the same variable, the application uses the last value it finds.

    Refer to the [sample `.env` file](https://github.com/Sitecore/jss/blob/release/19.0.0/samples/nextjs/.env) for variable names and descriptions.

- Check that you have correctly [set up the API key](https://doc.sitecore.com/xp/en/developers/hd/19/sitecore-headless-development/create-a-sitecore-services-client-api-key.html "Create a Sitecore services client API key").
- Check that your project's site definition and app definition are correct in your Sitecore configuration. Refer to the [sample app configuration](https://github.com/Sitecore/jss/blob/release/19.0.0/samples/nextjs/sitecore/config/JssNextWeb.config) for the list of required properties.
- Verify that you have set the [JSS Editing Secret](https://doc.sitecore.com/xp/en/developers/hd/19/sitecore-headless-development/walkthrough--connecting-a-next-js-jss-app-to-sitecore-editors.html "Walkthrough: Connecting a Next.js JSS app to Sitecore editors"). The `JSS_EDITING_SECRET`[value used by your Next.js app](https://github.com/Sitecore/jss/blob/cb32d3a21b87f488bd4bb5d311d556fd1f8354c4/samples/nextjs/.env#L18) must match the [value used by your Sitecore instance](https://github.com/Sitecore/jss/blob/cb32d3a21b87f488bd4bb5d311d556fd1f8354c4/samples/nextjs/sitecore/config/JssNextWeb.config#L37).
- Verify that the GraphQL endpoint is correct in [`package.json`](https://github.com/Sitecore/jss/blob/cb32d3a21b87f488bd4bb5d311d556fd1f8354c4/samples/nextjs/package.json#L12) and the Sitecore [app definition](https://github.com/Sitecore/jss/blob/cb32d3a21b87f488bd4bb5d311d556fd1f8354c4/samples/nextjs/sitecore/config/JssNextWeb.config#L72). Try opening the GraphiQL interface in a browser, using values from your config (`<sitecore hostname + graphQL endpoint>/ui?sc_apikey=<api key>`) to make sure the endpoint is working.

<details>
<summary><h2>Server-side JavaScript errors</h2></summary>

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:

```shell
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](https://github.com/tj/n) or [nvm](https://github.com/nvm-sh/nvm).

</details>

<details>
<summary><h2>Errors regarding SSL certificates</h2></summary>

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

> Error: unable to verify the first certificate
>
> Error: UNABLE*TO*VERIFY*LEAF*SIGNATURE
>
> UnauthorizedError: invalid signature

To resolve this error, [configure Sitecore CA certificates for Node.js](https://doc.sitecore.com/xp/en/developers/hd/19/sitecore-headless-development/walkthrough--configuring-sitecore-ca-certificates-for-node-js.html "Walkthrough: Configuring Sitecore CA certificates for Node.js").

</details>

<details>
<summary><h2>Errors deploying a JSS app locally</h2></summary>

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

```plaintext
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](https://kb.sitecore.net/articles/650791) for the solution.

</details>

<details>
<summary><h2>Data-fetching issues</h2></summary>

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](https://doc.sitecore.com/xp/en/developers/hd/19/sitecore-headless-development/preparing-the-list-of-pages-for-static-generation-or-export-in-jss-next-js-apps.html "Preparing the list of pages for static generation or export in JSS Next.js apps"). Try running this query directly in GraphiQL.

```graphql
# 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:

1. In the **Sitecore Control Panel**, use **Populate Solr Managed Schema** to populate the Solr Schema.
2. In the **Sitecore Control Panel**, use **Indexing Manager** to rebuild indexes.
3. Check that your content items have versions for the language you're trying to query.

</details>

<details>
<summary><h2>GraphiQL is blank, and developer tools show "Error: Mode graphql failed to advance stream"</h2></summary>

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.

![GraphiQL error Mode graphql failed to advance stream](https://doc.sitecore.com/api/markdown-image/xp/en/developers/hd/19/sitecore-headless-development/images/graphiql-error1.png)

To solve the problem:

1. Clear all local storage from the relevant tab.

    ![Clear the local storage for the Chrome tab with errors](https://doc.sitecore.com/api/markdown-image/xp/en/developers/hd/19/sitecore-headless-development/images/graphiql-error1-solution1.png)

2. In Chrome's task manager, kill the process before it can write to local storage again.

    ![Kill the process for the Chrome tab with errors](https://doc.sitecore.com/api/markdown-image/xp/en/developers/hd/19/sitecore-headless-development/images/graphiql-error1-solution2.png)

</details>

<details>
<summary><h2>Error "XmlException: Root element is missing" in GraphiQL</h2></summary>

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

![GraphiQL error XmlException: Root element is missing](https://doc.sitecore.com/api/markdown-image/xp/en/developers/hd/19/sitecore-headless-development/images/graphiql-error2.png)

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

</details>

<details>
<summary><h2>Error when trying to edit items in Sitecore</h2></summary>

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.

</details>

<details>
<summary><h2>Rendering host timeout issue in Experience Editor</h2></summary>

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:

```plaintext
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:

```xml
<!-- 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>

```

</details>

<details>
<summary><h2>GraphQL query error when trying to start the Next.js app using a Sitecore instance with SXA</h2></summary>

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:

- `/src/lib/sitemap-fetcher.ts`.
- `/src/lib/dictionary-service-factory.ts`.

</details>

<details>
<summary><h2>Errors when generating GraphQL introspection data</h2></summary>

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

> [!note]
> The script invoked internally by this command depends on having the `scjssconfig.json` file populated. To generate the file you must [connect your JSS app to Sitecore](https://doc.sitecore.com/xp/en/developers/hd/19/sitecore-headless-development/walkthrough--connecting-a-code-first-jss-next-js-application-to-sitecore.html "Walkthrough: Connecting a code-first JSS Next.js application to Sitecore").

</details>

## Vercel is unable to show data from a local Sitecore environment

If you are using [ngrok](https://ngrok.com/) to expose your local Sitecore endpoint to Vercel, verify that you are using the `host-header` flag. For example,

```shell
ngrok http -host-header=rewrite <your-local-url>

```

<details>
<summary><h2>App fails to render on Vercel after 18.0.0 upgrade</h2></summary>

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:

1. Make sure you choose the right page source file and that you only have one catch-all, dynamic route in `src/pages`
    - If using server-side rendering, keep `src/path/[[...path]].SSR.tsx` and rename it to `[[...path]].tsx`
    - If using static generation, delete `src/path/[[...path]].SSR.tsx`.
2. Redeploy your source code.

</details>

<details>
<summary><h2>Known Issue: Error in Experience Editor when attempting to type in an empty text field</h2></summary>

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

```plaintext
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.

</details>