Skip to main content
Version: 3.x

Troubleshooting

This page contains the most common errors you may encounter, along with information that will help to solve them quickly.

Server Issues​

Problem: Server is not starting​

If you're unable to prepare or start your application, follow these troubleshooting steps:

1. Check Console Output​

  • Review console output for error messages and stack traces
  • Look for any information that may help identify the issue

2. Verify Installation Steps​

  • Ensure you've followed all steps in the Getting Started guide
  • Missing steps or configuration details can prevent the server from starting properly

3. Clear the local redis DB​

  • Run redis-cli flushall

4. Clean and Reinstall Dependencies​

  • Remove the .front-commerce and node_modules directories: 
    rm -rf .front-commerce node_modules
  • Reinstall dependencies: 
    npm install
  • Try starting the server again… ¯\_(ツ)_/¯

Authentication issue​

Problem: Not logged in after entering valid credentials​

If you're experiencing login issues despite entering correct credentials, follow these troubleshooting steps:

1. Check Console Output​

  • Look for error messages and stack traces in your console
  • These often provide valuable debugging information
  • Clear your browser cookies
  • Verify that the response includes a cookie with the correct domain
  • Check if cookies are being properly set and stored. Look for connect.sid cookie

3. Configuration Verification​

  • Confirm that backend secrets are correctly configured

Problem: Infinite redirects when visiting any page​

If you're experiencing infinite redirections when accessing pages, follow these troubleshooting steps:

1. Check Console Output​

  • Look for error messages and stack traces in your console
  • These often provide valuable debugging information

2. Shop Detection Issues​

If the problem is related to shop detection mechanism:

  • Enable configuration debug mode: 
    DEBUG="front-commerce:config"
  • Verify configuration:
    • Ensure URLs in config/stores.js are valid
    • Verify if logged url matches browser URL

3. Proxy Configuration​

If the URL contains unexpected port numbers:

  • Configure server proxy/load balancer to add required headers:
    • X-Forwarded-Proto
    • X-Forwarded-Port
    • X-Forwarded-For

4. HTTPS Redirection Issues​

If experiencing unwanted HTTPS redirects:

  • For Production Servers:

    • Important: Implement proper HTTPS support
    • This is crucial for:
      • Security
      • SEO
      • User trust

  • For Development/Testing:

Problem: Products with slash in SKU return 404 errors​

If you're experiencing 404 errors or cannot access products that have a forward slash (/) in their SKU, follow these troubleshooting steps:

Server Configuration​

For Apache servers:

For Nginx servers:

Additional Resources​

Client-Side Issues​

Problem: JavaScript is not loading on the site​

If you're experiencing JavaScript loading issues on your site, follow these troubleshooting steps:

1. Browser Compatibility​

  • Identify your browser version and details
  • Check browser compatibility:
    • Review the browserslist configuration in your package.json or run pnpm dlx browserslist
    • Verify if your browser is supported by the defined list
    • Find out more here.

2. Error Investigation​

  • Check for errors in browser's Developer Tools console

Problem: CSS disappearing in development mode​

Since version 3.4

If you're experiencing CSS disappearing in development environment (not in production), follow these troubleshooting steps:

1. Understanding the Issue​

  • This is a known React issue

  • Only affects development environment

  • Production builds are not impacted

  • Fixed in React's canary release channel

    note

    Since Front-Commerce 3.10, React package has been updated.

2. Solution​

Use package overrides to pin React version:

package.json
{
  "dependencies": {
    "react": "18.3.0-canary-...",
    "react-dom": "18.3.0-canary-..."
  },
  "overrides": {
    "react": "18.3.0-canary-...",
    "react-dom": "18.3.0-canary-..."
  }
}
info

This approach is similar to Next.js's internal React version management

Additional Resources​

Data and API​

Problem: Unexpected data returned from GraphQL server​

If you're receiving unexpected data from your GraphQL queries, follow these troubleshooting steps:

1. Verify Query Behavior​

  • Test the same query in /graphql playground
    • Note: Only available when FRONT_COMMERCE_ENV !== "production"
  • Compare results between playground and application

2. Debug HTTP Calls​

  • Start server with HTTP debugging: 
    DEBUG=axios pnpm dev
    or
    .env
    DEBUG="axios"
  • Monitor HTTP calls to remote systems
  • Reproduce calls manually to verify remote API responses

3. Cache Verification​

  • Ensure cache data is current
  • For Redis users:

4. Resolver Investigation​

  • Use the debugger (or add console.log() statements) in GraphQL resolvers
  • Track data transformation through resolver chain
  • Identify where data modifications occur

Integration Issues​

Problem: Magento2 returns "The signature is invalid" error​

If you're receiving a 401 HTTP Code with the message "The signature is invalid. Verify and try again" from Magento2, particularly with Admin loader features, follow these troubleshooting steps:

1. OAuth Configuration​

  • Verify OAuth settings are correct
  • Test functionality:
    • Try viewing orders from a Customer account
    • Success indicates basic OAuth is working

2. Magento Patches​

If you're still experiencing issues after following these steps, please contact us.

Problem: Magento 2 GraphQL class not found error​

If you're encountering the error Class Magento\GraphQl\Model\Query\ContextExtensionInterfaceFactory does not exist when running GraphQL queries in Magento 2, follow these troubleshooting steps:

1. Identify the Issue​

  • This error typically occurs with queries like: 
    {
      productsBySkus(skus: ["24-UB02"]) {
        sku
      }
    }
  • Common in developer environment after running setup:di:compile

2. Resolution Steps​

For Developer Mode:

  • Remove compiled files: 
    rm -rf generated/{code,metadata}
  • Note: Code compilation is not needed in developer mode

Still Having Issues?​

If you've followed the troubleshooting steps and are still experiencing problems, our support team is here to help.

Please contact our support team with:

  • Steps you've already taken
  • Relevant error messages
  • Environment details
  • Any additional context that might help us assist you better