Sign Up
  1. Znode
  2. Solution home
  3. Developer Documentation - V10
  4. API Development - V10

React App & API - Troubleshooting gudelines

TABLE OF CONTENTS

Introduction

This article helps developers and customers to debug and troubleshoot issues and resolve common issues in the Commerce portal application. This guide is intended for developers, testers, and technical users involved in building or maintaining React applications. By following a systematic debugging process, you can effectively identify the root cause of issues and implement the appropriate fixes to ensure a smooth and efficient development experience.

This article is outlined into two main sections one is for troubleshooting the issues and its history, and another is for developers to debug the issue in a commerce portal,webstore, multifront. This document outlines a structured approach to troubleshooting common issues encountered while working with React applications. React is a powerful JavaScript library for building user interfaces, but like any complex system, it can present challenges during development and runtime. Problems such as component rendering failures, incorrect state management, broken API calls, unexpected behavior due to hooks, or build issues can disrupt the app's functionality/application.


Troubleshooting & Debugging(Development)

Prerequisites

Before troubleshooting the issues in a React application, make sure you have the following tools, resources, and details ready:

  • Having knowledge on API applications like Webstore,CP, multi front, Plugin APIs and its features.
  • Having knowledge on React framework& javascript  as CP api is developed in React 
  • Understanding of REST APIs: Familiarity with concepts like HTTP methods (GET, POST, PUT, DELETE), status codes (2xx, 4xx, 5xx), headers (Authorization, Content-Type), and data formats (JSON, XML).
  • API Documentation(stoplight  documentation https://apidocs.znode.com/) - This is the most crucial resource. It provides details on:
    • API Endpoints (URLs)
    • HTTP Methods (GET, POST, PUT, DELETE, etc.)
    • Required/Optional Parameters (query, path, or body params)
    • Request/Response Format (typically JSON; sometimes XML)
    • Authentication Details (e.g., Bearer token, API keys, OAuth)
    • HTTP Status Codes and their meanings
    • Error Format (structure of error messages or codes)
    • Rate Limits, Versioning, and any special headers
    • API Documentation can be found at Znode | Stoplight
  • API Credentials: Valid API keys, tokens, or user credentials required for authenticating API requests.
  • Access:
    • Access to the Znode Admin UI.
    • Potentially, access to server logs (application logs, web server logs, database logs), depending on the issue and your deployment setup.
    • Access to the Znode codebase (if debugging custom extensions or needing to trace core functionality).
  • Tools:
    • An API Client (e.g., Postman, Insomnia).
    • Browser Developer Tools (Network tab).
    • Text Editor or IDE (e.g., VS Code, Visual Studio).
    • Optional: Network traffic analysis tools (e.g., Fiddler, Wireshark).

Setup for local environment:


Please refer to the respective application setup guides to set up the local dev environments to debug the issues.

UI Troubleshooting Guidelines

Follow these steps in order to methodically diagnose the problem:

  • Verify the Basics:
    • Is your network connected and stable? Simple check, but essential. Can you access other websites or services?
    • Is the API server address correct? Double-check the base URL and the specific endpoint path against the documentation.
    • Is the API service operational? Check the API provider's status page (if available) or try a very basic, known-working endpoint (like a /status or /health check if provided).
    • Follow a structured approach:
  • Examine the Request:
    • Use an API Client (like Postman or  This helps isolate whether the issue is in your application code or the request itself.
    • Check the HTTP Method: Are you using GET for fetching, POST for creating, PUT for updating, etc., as specified in the documentation?
    • Verify the URL: Is the path correct? Are any path parameters included correctly?
    • Check Query Parameters: Are names spelled correctly? Are values formatted correctly (e.g., date formats, escaped characters)?
    • Inspect Headers:
      • Are required headers present? (e.g., Content-Type, Accept, Authorization).
      • Are headers correctly formatted? (e.g., Authorization: Bearer your_token).
    • Review the Request Body: (For POST, PUT, PATCH)
      • Is the format correct (e.g., valid JSON, XML)? Use a validator if unsure.
      • Does the structure match the documentation?
      • Are all required fields included?
      • Are data types correct? (e.g., sending a number as a string).
  • Examine the Response:
    • Check the HTTP Status Code: This is the primary indicator of the request's outcome. (See Section 4 for common codes).
    • Read the Response Body: Even for error codes (4xx, 5xx), the response body often contains a more detailed error message or code specific to the API. Read it carefully!
    • Inspect Response Headers:
      • Check for Content-Type to confirm the response format.
      • Look for error-specific headers or rate-limit information (X-RateLimit-...).
      • Check caching headers if applicable.
  • Consult the API Documentation (Again): With the request and response details in hand, revisit the documentation for the specific endpoint, method, and error code received. The documentation might explain the exact meaning of the error response body or provide troubleshooting tips for that specific scenario.
  • Look at Logs:
    • Client-Side Logs: Check your application's logs for any errors occurring before or after the API call is made.
    • Server-Side Logs: If you manage the API or have access, server logs provide insights into what happened from the API's perspective (error traces, specific request details, database errors, etc.).
  • Isolate the Problem:
    • Can you reproduce the issue consistently? If not, what factors might make it intermittent (timing, data, load)
    • Does it happen only with specific data? Try different input values.
    • Does it happen only in a specific environment or network? (e.g., only from production, only from behind a firewall).
    • Does it happen only when called by your application code? (Compare results with API client tools).
  • Inspect Elements
    • Use browser developer tools to examine HTML/CSS.
    • Check Console and Network Tabs – Look for red flags such as failed requests or script errors.
    • Test Across Browsers/Devices – Ensure consistency.
    • Clear Cache – Sometimes issues are due to outdated assets.
    • Validate API Responses – Confirm data is coming in as expected.
    • Look at Version History – If the issue is new, recent changes might have introduced it.

UI Troubleshooting Guidelines

  • Problem Details: Before debugging, be ready to answer:
    • What endpoint is being called?
    • What HTTP method is used (GET, POST, etc.)?
    • What headers, params, and body are being sent?
    • What's the exact error or unexpected behavior?
    • Was it working previously? If so, when did it break?
    • Can you consistently reproduce the issue?
  • Access to console logs

    React apps don’t have “logs” like server-side apps, but you can:

    • Use console.log() or console.error() to trace data before/after the API call

    • Use VS Code Debugger to set breakpoints

    • Monitor API responses using Chrome DevTools (check the Network tab)

    • Check the browser Console tab for caught and uncaught errors

  • Terminal checks

    • Start your React app using: npm start

    • Observe the terminal output (in VS Code's terminal or your system terminal).

    • Look for: Build errors, Warnings, Any stack traces (useful to trace crashes or module errors)

  • Developer tools -console tab checks.

    • Go to the Console tab:

      • Check for JavaScript runtime errors.

      • Check for unhandled promise rejections.

  • Developer tools -Network tab checks.

    • Inspect failed API requests.

    • View request headers, payloads, and server responses.

    • Check for CORS errors, 401 Unauthorized, 500 Internal Server Error, etc

  • Validate Environment Files (.env)

    • Open your React app’s .env file (typically in the root folder).

    • Ensure critical environment variables are properly defined and spelled correctly.

    • Typical important keys to check:

      • REACT_APP_API_URL

      • REACT_APP_IS_DEBUGGING

      • REACT_APP_ENABLE_CACHE

      • REACT_APP_AUTH_TOKEN

  • Use VS Code Debugger (Optional Advanced Step)

    • Set breakpoints directly in your .jsx, .tsx, or .js files.

    • Launch the VS Code Debugger (Run and Debug tab ➔ Start Debugging).

    • Step through your code execution to capture errors or data mismatches at runtime.

  • Log Types You Can Observe in React Development

    Log TypeWhat It RepresentsWhere to Find
    Build LogsCompilation results, dependencyTerminal (VS Code)
    Console LogsJavaScript runtime logs, debug information, errors, and warningsBrowser DevTools → Console
    Network LogsAPI request/response details, HTTP error codes (404, 500, etc.)Browser DevTools → Network
    Runtime ErrorsReact-specific errors (invalid props, state updates, hooks misuse)Console & Terminal Output

    • Log Actions in React Development (VS Code)

      • View Logs

        • View Console Logs:

          • Open the Console tab in your browser’s Developer Tools (F12 ➔ Console).

          • Review runtime logs, errors, warnings, and info/debug outputs generated during app execution.

        • View Terminal Logs:

          • Observe the VS Code Terminal (where npm start is running).

          • See build-time warnings, compilation issues, or environment-related errors.

      • Configure Logs

        • Control Log Levels Manually in Code:

          • Use different console methods to differentiate log types:

            • console.log() for general info

            • console.warn() for warnings

            • console.error() for errors

        • During development, you can toggle logging verbosity by adding a debug flag in .env:

          • REACT_APP_IS_DEBUGGING=true

          • if (process.env.REACT_APP_IS_DEBUGGING === 'true') {console.log("Debug Info:", data);}

      • Purge Logs

        • Clear Console Logs:

          • Right-click inside the browser's Console ➔ Click "Clear Console"

        • Clean Up Debug Logs in Code

          • Remove or comment out the console. log (), console.warn(), and console.error() before building for production.

          • Alternatively, implement a custom logger that automatically disables logging when in production mode.

    • Visual Editor Crashes After Widget Integration

      • Checklist:

        • Wrap render logic in error boundaries or use defensive coding for undefined/null props.

        • Log received props and config values using console.log or debugger.

        • Use try-catch for custom render logic, especially when looping through dynamic data.


UI - Debugging

  • Debug steps
    • Navigation
      • Use DevTools → Network tab
      • Check failed API requests: look for 401/500 errors
      • Confirm API_KEY and API_URL in the .env files are correctly configured
      • If CORS issues arise, confirm headers and domains are correctly whitelisted on the backend
    • Broken Routing or 404 Pages
      • Ensure routes are defined in your routes. ts or pages structure
      • Validate SEO slugs and rewrites are set in Next.js config if using dynamic routing
      • Check if preview URL parameters are missing or malformed
    • Real-Time JSON Preview Not Working
      • Make sure the data/ folder is present and writable in the root directory
      • Confirm that Page Builder can write JSON to data/
      • Restart Webstore to read the latest JSON blocks
    • Pre-Commit Hook Overview
      Our repo is configured with a husky pre-commit hook that performs the following steps:
      • Spell Check (using cspell)
      • Linting (npm run lint)
      • Build Check (npm run build)
      • Commit Message Validation (via commitlint)
    • Step-by-Step Troubleshooting
      • Spell Checker Fails Immediately
        • If you see something like: Spell check failed. Please fix the spelling errors before committing
        • Fix: Run the command manually to identify errors:

          npx cspell $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx|json|md|html|css|scss)$')

        • Identify false positives or legit typos.

        • Fix the typos OR add valid words (e.g., product names, acronyms, etc.) to the cspell.json:

      • Lint or Build Fails
        This can happen due to proper nouns or technical words being flagged.
        • ❌ Linting failed. Please fix the issues before committing.
        • ❌ Build failed. Please fix the issues before committing
        • Fix: Run manually:
          npm run lint
          npm run build
    • Clear React Build Cache and Reset the Environment (npm setup)
      • Clear React Cache
        • If you're facing weird build issues, stale environment variables, or unexplained bugs, reset your React app environment with these steps:
      • Cleanup & Reset Steps
        • Delete node_modules folder (removes all installed packages): rm -rf node_modules
        • Delete the lock file (package-lock.json or yarn.lock): rm package-lock.json
        • Clear npm cache (optional but recommended): npm cache clean-- force
        • Reinstall project dependencies: npm install
        • Start your React app again: npm start
      • ?️ Summary of Commands
        • rm -rf node_modules
        • rm package-lock.json
        • npm cache clean-- force
        • npm install
        • npm start

API Debugging

Step 1: Verify the API Request (Client-Side & API Client)

  • Endpoint URL:
    • Is the URL correct? Check for typos.
    • Is it pointing to the correct environment (Dev, QA, Staging, Prod)?
    • Does it include the correct Znode domain and API base path?
  • HTTP Method:
    • Is the correct method being used (e.g., using GET for retrieving data, POST for creating, PUT for updating)? A common mistake is using GET instead of POST with a request body.
  • Headers:
    • Authorization: Is the token/API key correct, valid (not expired), and formatted properly (e.g., Bearer <token>)? Are the associated user/credentials active and have the necessary permissions?
    • Content-Type: Does it match the format of the request body (e.g., application/json)?
    • Accept: Does it specify the desired response format (e.g., application/json)?
  • Request Body/Payload (for POST, PUT, PATCH):
    • Is the data format correct (e.g., valid JSON)? Use a JSON validator.
    • Are all required fields present? Consult the API documentation.
    • Are data types correct (string, integer, boolean)?
    • Is the structure correct (nesting, arrays)?
    • Check for case sensitivity issues in field names.
    • Tool: Use Postman or Insomnia to manually construct and send the request, isolating it from the calling application.

Step 2: Analyze the API Response

  • HTTP Status Code:
    • 2xx (Success): The request was successful, but the data might still be incorrect. Check the response body. (e.g., 200 OK, 201 Created, 204 No Content).
    • 4xx (Client Error): The issue is likely with the request itself.
      • 400 Bad Request: Often validation errors. Check the response body for details.
      • 401 Unauthorized: Authentication failed. Check API keys/tokens.
      • 403 Forbidden: Authentication succeeded, but the user/key lacks permission for the action/resource. Check Znode roles/permissions.
      • 404 Not Found: Endpoint URL is wrong, or the requested resource (e.g., product ID) doesn't exist.
      • 405 Method Not Allowed: Using the wrong HTTP method for the endpoint.
      • 429 Too Many Requests: Rate limiting is being applied.
    • 5xx (Server Error): The issue is on the Znode server side.
      • 500 Internal Server Error: Generic server error. Requires checking server logs.
      • 502 Bad Gateway / 503 Service Unavailable / 504 Gateway Timeout: Often indicate issues with infrastructure, load balancers, or the application server being down or overloaded.
  • Response Body:
    • Does it contain an error message? Read it carefully – Znode often provides specific validation details in the response for 4xx errors.
    • Is the data structure as expected?
    • Is the returned data correct? If not, it might be a configuration issue or a bug in the API logic.
    • Is the response empty when data was expected?
  • Response Headers:
    • Check Content-Type to ensure it matches the format of the response body.
    • Look for custom headers that might provide debugging information or rate limiting details.


Step 3: Check Znode Configuration (Admin UI)

  • API Settings: Verify API settings in the Znode Admin console. Are APIs enabled? Are the correct keys configured
  • Permissions & Roles: Check the roles and permissions assigned to the user account or API key being used for authentication. Do they have access to the specific API endpoint and the data involved (e.g., specific catalog, store)
  • Store Settings: Ensure relevant features, catalogs, pricing, inventory, etc., are configured correctly in the Znode Admin for the store context being used in the API call.
  • Data Existence: Verify that the specific data being requested or manipulated (e.g., Product SKU, User ID, Order Number) exists in the system and is in the expected state.
  • Customizations/Extensions: Could a custom extension or code modification be interfering with the core API functionality?

Step 4: Examine Server Logs

  • Znode Application Logs: These are critical for diagnosing 5xx errors. Look for:
    • Stack traces indicating exceptions.
    • Error messages related to database connectivity, permissions, or code execution.
    • Detailed logging for specific API requests (if enabled).
    • (Log location depends on Znode version and deployment configuration - check platform documentation or deployment specifics).
  • Web Server Logs (IIS, Nginx, etc.): Check for HTTP errors that might not reach the Znode application (e.g., configuration issues, failed requests).
  • Database Logs: If suspecting database issues (slow queries, deadlocks, errors), check the SQL Server logs (if accessible).
  • Windows Event Viewer (if applicable): Look for application or system-level errors that might impact the Znode application pool or web server.

Step 5: Utilize Advanced Tools & Techniques

  • Browser Developer Tools: Use the "Network" tab to inspect the actual API requests being made by the frontend application. Compare these with your successful Postman requests to spot discrepancies. Check the "Console" tab for related frontend errors.
  • Code-Level Debugging (Visual Studio): If you have access to the Znode source code or are debugging a custom extension, attach a debugger (like Visual Studio) to the Znode process (w3wp.exe for IIS). Set breakpoints to step through the code execution for the specific API request and inspect variable values.
  • Network Sniffers (Fiddler, Wireshark): For complex network issues, SSL/TLS problems, or to capture traffic between different services. Fiddler is often easier for HTTP/S traffic analysis.
  • Database Profiling: Use SQL Server Profiler or similar tools to trace database queries executed by the API call, checking for performance bottlenecks or errors.

Production Troubleshooting

To troubleshoot the production issues, we have the following options.

  • Application logs
    • To access the application logs, please log in to the znode admin application with the admin user.
  • Navigate to Devcenter-> Application logs.
  • We have various categories and types of logs to verify the issues, which you can enable from the logs configuration.
    • Categories
      • Event logs
      • Database logs
      • Integration logs
    • Types
      • Error
      • Info
      • Warning
      • Debug logs
  • Please filter the issues by the type of application or service and fetch the respective logs. Then we can get the actual error details to identify the issues.
  • To fix the issues by error type, please refer to the Issues History to know the fix if we have fixed it earlier.
  • Otherwise, we need to find the RCA of the issue, and it needs to be fixed. If it is based on below categories.
    • Environmental issue - Can be fixed via the DevOps & It team via the support team.
    • Data issues - Can validate data configurations and BD changes and correct it.
    • Code & braking changes issues - Need to reach out to support team to get the fix.
    • Functional issues - verify the application configurations 
    • Configuration issues - this can happen due to wrong configurations
    • Any other issues- Reach Znode support team.

Debugging for API Issues

Step 1: Verify the API Request (Client-Side & API Client)

  • Endpoint URL:
    • Is the URL correct? Check for typos.
    • Is it pointing to the correct environment (Dev, QA, Staging, Prod)?
    • Does it include the correct Znode domain and API base path?
  • HTTP Method:
    • Is the correct method being used (e.g., using GET for retrieving data, POST for creating, PUT for updating)? A common mistake is using GET instead of POST with a request body.
  • Headers:
    • Authorization: Is the token/API key correct, valid (not expired), and formatted properly (e.g., Bearer <token>)? Are the associated user/credentials active and have the necessary permissions?
    • Content-Type: Does it match the format of the request body (e.g., application/json)?
    • Accept: Does it specify the desired response format (e.g., application/json)?
  • Request Body/Payload (for POST, PUT, PATCH):
    • Is the data format correct (e.g., valid JSON)? Use a JSON validator.
    • Are all required fields present? Consult the API documentation.
    • Are data types correct (string, integer, boolean)?
    • Is the structure correct (nesting, arrays)?
    • Check for case sensitivity issues in field names.
    • Tool: Use Postman or Insomnia to manually construct and send the request, isolating it from the calling application.

Step 2: Analyze the API Response

  • HTTP Status Code:
    • 2xx (Success): The request was successful, but the data might still be incorrect. Check the response body. (e.g., 200 OK, 201 Created, 204 No Content).
    • 4xx (Client Error): The issue is likely with the request itself.
      • 400 Bad Request: Often validation errors. Check the response body for details.
      • 401 Unauthorized: Authentication failed. Check API keys/tokens.
      • 403 Forbidden: Authentication succeeded, but the user/key lacks permission for the action/resource. Check Znode roles/permissions.
      • 404 Not Found: Endpoint URL is wrong, or the requested resource (e.g., product ID) doesn't exist.
      • 405 Method Not Allowed: Using the wrong HTTP method for the endpoint.
      • 429 Too Many Requests: Rate limiting is being applied.
    • 5xx (Server Error): The issue is on the Znode server side.
      • 500 Internal Server Error: Generic server error. Requires checking server logs.
      • 502 Bad Gateway / 503 Service Unavailable / 504 Gateway Timeout: Often indicate issues with infrastructure, load balancers, or the application server being down or overloaded.
  • Response Body:
    • Does it contain an error message? Read it carefully – Znode often provides specific validation details in the response for 4xx errors.
    • Is the data structure as expected?
    • Is the returned data correct? If not, it might be a configuration issue or a bug in the API logic.
    • Is the response empty when data was expected?
  • Response Headers:
    • Check Content-Type to ensure it matches the format of the response body.
    • Look for custom headers that might provide debugging information or rate-limiting details

Step 3: Check Znode Configuration (Admin UI)

  • API Settings: Verify API settings in the Znode Admin console. Are APIs enabled? Are the correct keys configured
  • Permissions & Roles: Check the roles and permissions assigned to the user account or API key being used for authentication. Do they have access to the specific API endpoint and the data involved (e.g., specific catalog, store)?
  • Store Settings: Ensure relevant features, catalogs, pricing, inventory, etc., are configured correctly in the Znode Admin for the store context being used in the API call.
  • Data Existence: Verify that the specific data being requested or manipulated (e.g., Product SKU, User ID, Order Number) actually exists in the system and is in the expected state.
  • Customizations/Extensions: Could a custom extension or code modification be interfering with the core API functionality?

Step 4: Examine Server Logs

  • Znode Application Logs: These are critical for diagnosing 5xx errors. Look for:
    • Stack traces indicating exceptions.
    • Error messages related to database connectivity, permissions, or code execution.
    • Detailed logging for specific API requests (if enabled).
    • (Log location depends on Znode version and deployment configuration - check platform documentation or deployment specifics).
  • Web Server Logs (IIS, Nginx, etc.): Check for HTTP errors that might not reach the Znode application (e.g., configuration issues, failed requests).
  • Database Logs: If suspecting database issues (slow queries, deadlocks, errors), check the SQL Server logs (if accessible).
  • Windows Event Viewer (if applicable): Look for application or system-level errors that might impact the Znode application pool or web server


Step 5: Utilize Advanced Tools & Techniques

  • Browser Developer Tools: Use the "Network" tab to inspect the actual API requests being made by the frontend application. Compare these with your successful Postman requests to spot discrepancies. Check the "Console" tab for related frontend errors.
  • Code-Level Debugging (Visual Studio): If you have access to the Znode source code or are debugging a custom extension, attach a debugger (like Visual Studio) to the Znode process (w3wp.exe for IIS). Set breakpoints to step through the code execution for the specific API request and inspect variable values.
  • Network Sniffers (Fiddler, Wireshark): For complex network issues, SSL/TLS problems, or to capture traffic between different services. Fiddler is often easier for HTTP/S traffic analysis.
  • Database Profiling: Use SQL Server Profiler or similar tools to trace database queries executed by the API call, checking for performance bottlenecks or errors.

Qucik Link:

Webstore Issues

API Issues

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.

API Development - V10