--- title: "Troubleshooting JSS Next.js apps" slug: "troubleshooting-jss-next-js-apps" abstract: "Describes how to avoid errors and gives 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/23/sitecore-headless-development/debug-logging-in-jss-apps.html "Debug logging in JSS apps"). You can prevent most errors by doing the following: - 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 for variable names and descriptions. - Check that you have correctly [set up the API key](https://doc.sitecore.com/xp/en/developers/hd/23/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 [Sitecore app configuration](https://github.com/Sitecore/jss/blob/master/packages/create-sitecore-jss/src/templates/nextjs/sitecore/config/%7B%7BappName%7D%7D.config) for the list of required properties. - Verify that you have set the [JSS Editing Secret](https://doc.sitecore.com/xp/en/developers/hd/23/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 must match the value used by your Sitecore instance. - Verify that the GraphQL endpoint is correct in `package.json` and the Sitecore app configuration. Try opening the GraphQL IDE in a browser, using values from your config (`/ui?sc_apikey=`) to make sure the endpoint is working.

Server-side JavaScript errors

 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 might 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).

Errors regarding SSL certificates

 If you are working with a local Sitecore instance using a privately signed certificate, you might experience the following error: ```plaintext 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/23/sitecore-headless-development/walkthrough--configuring-sitecore-ca-certificates-for-node-js.html "Walkthrough: Configuring Sitecore CA certificates for Node.js").

Errors deploying a JSS app locally

 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.

Data-fetching issues

 Building and rendering a JSS Next.js app depends 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. You can use the GraphQL IDE at `/ui?sc_apikey=` to diagnose issues with the data-fetching process. To support static generation functionality, the Next.js JSS app [uses a GraphQL query to retrieve Sitecore paths](https://doc.sitecore.com/xp/en/developers/hd/23/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 the following query in the GraphQL IDE: ```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 are querying.

Error when trying to edit items in Sitecore

 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.

Rendering host timeout issue in Experience Editor

 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 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 10000 ```
## Connection to rendering host failed due to payload size If you receive the `(413) Payload Too Large` error when sending a payload to Experience Edge, we recommend you increase the `sizeLimit` property of your app, which is set to 2MB by default in sample Next.js apps. You'll need to make this change in the following files: - `\src\pages\api\editing\render.ts` - `\src\pages\api\editing\[key].ts` The following example represents the relevant part of `render.ts` after increasing the payload size limit to 5MB: ```ts ... export const config = { api: { bodyParser: { sizeLimit: "5mb", }, responseLimit: false, }, }; ... ```

GraphQL query error when trying to start the Next.js app using a Sitecore instance with SXA

 If you have an SXA integration with an SXA collection of Headless Sites and you deploy Next.js items to it, 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 the SXA collection of Headless Sites 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/plugins/graphql-sitemap-service.ts`. - `/src/lib/dictionary-service-factory.ts`.

Errors when generating GraphQL introspection data

 If the GraphQL schema changes, you must regenerate GraphQL introspection data. In the sample app, you regenerate introspection data using the `jss graphql:update` command. > [!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/23/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").

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

Sitecore images do not load on localhost

 If your Sitecore images do not load when using a `localhost` domain for the application, it is likely because you are trying to request images through the Next.js proxy, resulting in the error: `500 - Invalid URI: The hostname could not be parsed`. To load Sitecore images on a `localhost` domain, you must set the `IncludeServerUrlInMediaUrls` attribute of the contents resolver to `true` to include the Sitecore URL in the image URL. For example: ```xml true ``` With this configuration in place, the application requests the images directly from Sitecore. > [!important] > In production environments, you must change the value of the `IncludeServerUrlInMediaUrls` attribute to `false`.

Experience Editor integration breaks because of a protocol mismatch error

 When hosting the Next.js application on platforms other than Vercel, if the integration with Experience Editor stops working because of a protocol mismatch error, [override default protocols using the EditingRenderMiddleware](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/override-default-protocols-using-the-editingrendermiddleware-in-next-js-jss-apps.html "Override default protocols using the EditingRenderMiddleware in Next.js JSS apps").

Editing data cache miss and intermittent 500 errors in Experience Editor

 When hosting the Next.js application on platforms other than Vercel, you might see cache miss errors in the Node.js environment. For example: ```plaintext 2022-10-12 `16:27`:42: Error: Unable to get editing data for preview {"key":"0518d8c6-b7ca-4c73-86c2-a29d971ebeab-2xqnbg0jpx","serverUrl":"https://your-url.com"}     at SitecorePagePropsFactory.createPreviewModePage (/opt/web/.next/server/chunks/9694.js:1190:17)     at runMicrotasks ()    at processTicksAndRejections (internal/process/task_queues.js:95:5)     at async SitecorePagePropsFactory.create (/opt/web/.next/server/chunks/9694.js:1174:14)     at async getServerSideProps (/opt/web/.next/server/pages/[[...path]].js:1952:17)     at async Object.renderToHTML (/opt/web/.next/node_modules/next/dist/server/render.js:555:20)     at async doRender (/opt/web/.next/node_modules/next/dist/server/base-server.js:1406:38)     at async /opt/web/.next/node_modules/next/dist/server/base-server.js:1501:28     at async /opt/web/.next/node_modules/next/dist/server/response-cache.js:`63:36` ``` The issue causes a 500 error in the Content Management instance, such as: ```plaintext 3112 `16:27`:42 ERROR The remote server returned an error: (500) Internal Server Error. Exception: System.Net.WebException Message: The remote server returned an error: (500) Internal Server Error. 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) ``` Such errors are caused by the instability of the temporary directory used by the editing data cache. To resolve the errors, [override the default directory used by the disk-based editing cache implementation](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/override-the-default-directory-used-by-the-disk-based-editing-cache-implementation.html "Override the default directory used by the disk-based editing cache implementation").