Troubleshooting: Must Gather information for the Next.js store

This document provides the steps to address problems related to the Next.js store.

Problem

While working on the Next.js store, shoppers can encounter the following errors:
  1. An empty page returns after hitting the store URL, or the error message is displayed.
  2. The store landing page is not getting displayed.
  3. The specific store section is missing.
  4. The transaction server is responding as expected, but the store page is not rendering.

Procedure

To address the problems encountered while using the Next.js store, follow the steps given below:
  1. Collect the HAR file from the browser. To collect the HAR file:
    • Open developer tools in the browser.
    • Recreate the issue you came across.
    • Go to the Console tab. Right-click and select Save as to save and upload the file to support.
    • Go to the Network tab and select all. Right-click and select Save all as HAR with content.
  2. Enable the Trace Level Logging in the Next.Js store container with the following steps:
    • Capture the Next.Js store docker container name and run exec to run commands inside the container.docker exec -it container_name bash
    • Go to the /SETUP/bin directory and edit the utilities.sh file to update the LOG_LEVEL from info to trace.
    • Update the property as shown below and save the file.
      validateAndExportParameter LOG_LEVEL "trace"
    • Restart the docker container.
  3. Run the docker logs --follow container_id command. This command continues to stream the new output from the container's STDOUT and STDERR. Extract this information to a file and share the trace output.

What to do next

  • Analyze the HAR file.
  • Each API request has a response header with the header name X-Hcl-Next-Request-Id added to it. The value of this request ID is the randomly generated ID, which can be used to correlate this request from the HAR file to the same request in the logs file.
  • The screenshots below highlight this header from the browser's developer tool (captured in the HAR File) and the traces of the same API request captured in the logs file with the same request ID reference.
  • Once you have identified the API in the logs file using the request ID, you can also leverage the trace file to analyze and validate the API response code, error message, request parameters of the API and exception data (if any).
    Important: The Pages in the Next.js store use Server-side Rendering. For example, if a shopper navigates the store from Home Page to Furniture Category Page, his action will invoke a call to the Next.js server, as shown in the example below. This API call can be tracked on the browser HAR file. https://HOST:PORT/_next/data/L33Zz3N8r5Y3xQj5bZOxb/en-US/ruby/furniture.json?path=ruby&path=furniture
  • The above call to NextJs server will make server-side calls to the transaction server and query server APIs to fetch store, context, SEO, search or any other data required to render the page to the client.
  • These server-side calls can be traced in the logs file, which would show the API to the transaction/query server, the API's query parameters and the API's status code. For example, refer to a snippet of traces:
    {"level":"trace","time":"2024-04-05T04:26:37.402Z","requestId":"22ddf673-5105-4866-82e1-a65aecdb0c22","msg":"API response","status":200,"url":"https://app:5443/wcs/resources/store/0/seo/token","params":{},"query":{"q":"byUrlKeywordNames","urlKeywordName":["Next.js"]},"methodName":"tokenFindByUrlKeywordNames"}
{"level":"trace","time":"2024-04-05T04:26:37.403Z","requestId":"22ddf673-5105-4866-82e1-a65aecdb0c22","msg":"API request","url":"https://app:5443/wcs/resources/store/41/online_store","params":{},"query":{"q":"findOnlineStore","profileName":"IBM_Admin_All"},"methodName":"storeFindByQueryOnlineStore"}  
{"level":"trace","time":"2024-04-05T04:26:37.458Z","requestId":"22ddf673-5105-4866-82e1-a65aecdb0c22","msg":"API request","url":"https://es-db2.hclcomdev.com:30901/search/resources/api/v2/urls","params":{},"query":{"storeId":41,"identifier":["furniture"]},"methodName":"getV2CategoryResources1"}
{"level":"trace","time":"2024-04-05T04:26:37.926Z","requestId":"22ddf673-5105-4866-82e1-a65aecdb0c22","msg":"API response","status":200,"url":"https://es-db2.hclcomdev.com:30901/search/resources/api/v2/urls","params":{},"query":{"storeId":41,"identifier":["furniture"]},"methodName":"getV2CategoryResources1"}
{"level":"trace","time":"2024-04-05T04:26:37.931Z","requestId":"22ddf673-5105-4866-82e1-a65aecdb0c22","msg":"API request","url":"https://es-db2.hclcomdev.com:30901/search/resources/api/v2/categories","params":{"headers":{}},"query":{"storeId":"41","depthAndLimit":"11,11","contractId":["-41005"],"langId":"-1"},"methodName":"getV2CategoryResources"}
{"level":"trace","time":"2024-04-05T04:26:37.932Z","msg":"get: missed cache entry from node cache with key '@@#registerType:\"G\",,,\"@#_s:\\\"-1\\\",_d:@\\\"-41005\\\",,_a:\\\"11501\\\",_I:\\\"10502\\\",_H:\\\"CategoryToken\\\",_G:\\\"LivingRoomFurniture\\\",_C:\\\"41\\\",,\\\"BREADCRUMB\\\",\",', value %o"}
{"level":"trace","time":"2024-04-05T04:26:37.932Z","requestId":"22ddf673-5105-4866-82e1-a65aecdb0c22","msg":"API request","url":"https://es-db2.hclcomdev.com:30901/search/resources/api/v2/products","params":{"headers":{}},"query":{"storeId":"41","catalogId":"11501","langId":"-1","limit":1,"contractId":["-41005"],"categoryId":"10502"},"methodName":"findProducts"}
{"level":"trace","time":"2024-04-05T04:26:37.960Z","requestId":"22ddf673-5105-4866-82e1-a65aecdb0c22","msg":"API response","status":200,"url":"https://es-db2.hclcomdev.com:30901/search/resources/api/v2/categories","params":{"headers":{}},"query":{"storeId":"41","depthAndLimit":"11,11","contractId":["-41005"],"langId":"-1"},"methodName":"getV2CategoryResources"}

. . .