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

The IP stored in Magento is not the same as the customer's IP​

The expected behavior​

When you experience IPs from the front-commerce hosting instead of getting the customer IP stored in the order, you need to ensure your Magento provider is not changing the value of the X-Forwarded-For header.

How to troubleshoot it?​

To easily ensure if this value is altered you can temporarily add the following PHP script to the Magento instance at pub/fc-test-ip.php with the following content:

<?php echo "<pre>" . print_r($_SERVER, true) . "</pre>"; ?>

Then call it using curl:

curl -H "X-Forwarded-For: 66.66.66.66" https://<magento_url>/fc-test-ip.php | grep HTTP_X_FORWARDED_FOR

If you do not retrieve the IP passed in the X-Forwarded-For in the response, please contact your Magento provider to ensure this header and values pass through each proxy without being modified or removed.

Gitlab / Blackswift​

Problem: fatal: could not read from remote repository​

Here are some steps that one can follow to troubleshoot a pnpm install problem due to incorrect SSH authorization when cloning a private dependency (here Front-Commerce) using git:

  • Ensure you have added your SSH key in your Gitlab account
  • Run the command ssh -v git@gitlab.blackswift.cloud (or -vvv) to see if there are any connectivity issues or errors.
  • Check to make sure that the correct SSH key is being used for the private repository. This key should be added to the ssh-agent, which is responsible for managing SSH keys.
  • To check if the correct SSH key is being used, run the command ssh-add -l. This will list all of the keys that are currently managed by the ssh-agent.
  • If the correct SSH key is not being used, it can be added to the ssh-agent using the command ssh-add /path/to/private_key.
  • If the issue is still not resolved, it is possible that there is a problem with the ssh-agent itself. To fix this, try running the command eval "$(ssh-agent -s)" to start a new ssh-agent and then add the correct SSH key using the ssh-add command from the previous step.
  • If the problem persists after trying these steps, it may be necessary to check the ssh configuration files (located in the ~/.ssh directory) for any issues or misconfigurations.

If the problem persists, please contact us!

Additional resources​

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