Documentation

Troubleshooting

Common challenges with customization development, along with practical solutions.

If you need help with a technical question or need general guidance, you can contact us for help.

We strongly encourage and recommend using GitHub Discussions to communicate with us (commercetools) and with the community. You can ask questions, share ideas, showcase your work, etc.

Additionally, we also recommend checking for existing GitHub Issues that may be related to your problem before opening a new one.

General

This section details general recommendations, regardless of the customization type.

Browser support

commercetools officially supports the latest two versions of all major browsers (Google Chrome, Mozilla Firefox, Apple Safari, and Microsoft Edge), unless otherwise noted.

The following browsers are no longer supported:

  • IE 11 and older versions

We recommend that you keep your browser up to date for security reasons.

Custom Applications

This section details common issues and solutions for Custom Applications.

Granular permissions for local development

This feature is available from version 22.5.0 onwards.

This method requires additional configuration and setup and is only recommended for development teams with prior experience in Custom Application development and installation.

By default, developing a Custom Application requires you to be a member of the Administrators Team. However, for security reasons, your Organization might not be willing to grant administrator access to developers. In this case, an Organization can grant access using a regular team.

To enable this option, you must complete the following prerequisites in the Merchant Center (which can be done only with administrator rights):

  1. Configure the Custom Application in the Merchant Center

For local development the Custom Application does not have to be deployed, and Application URL is not relevant. Therefore, any acceptable value can be provided in the registration form.

  1. Assign the Application ID
  2. Install the Custom Application
  3. Create a team (or utilize an existing one)
  4. Obtain the teamId from the Merchant Center URL
  5. Invite users to the team
  6. Assign relevant permissions to the team

After completing these steps, you will have an applicationId and a teamId. You must provide these values for env.production.applicationId and env.development.teamId, respectively, in the Custom Application configuration file.

This process lets any member of the configured team log in and perform local development for the Custom Application.

Using a test or staging environment

During the development cycle of new features for a Custom Application, it can be helpful to showcase or test those new features before publishing them to the production environment. This can be accomplished using deployment previews which allow you to inspect different versions of a Custom Application.

The page keeps reloading itself

If the Merchant Center page keeps reloading itself when accessing a Custom Application, most likely, there's a misconfiguration of the entryPointUriPath. See Page reloading behavior for more information on debugging and solving this issue.

Session token expiration

In the browser, the session token is stored in a secure cookie named mcAccessToken and is valid for 30 days.

Custom Views

This section details common issues and solutions for Custom Views.

Granular permissions for local development

This method requires additional configuration and setup and is only recommended for development teams with prior experience in Custom Views development and installation.

By default, developing a Custom View requires you to be a member of the Administrators Team. However, for security reasons, your Organization might not be willing to grant administrator access to developers. In this case, an Organization can grant access using a regular team.

To enable this option, you must complete the following prerequisites in the Merchant Center (which can be done only with administrator rights):

  1. Configure the Custom View in the Merchant Center

For local development the Custom View does not have to be deployed, and Custom View URL is not relevant. Therefore, any acceptable value can be provided in the registration form.

  1. Assign the Custom View ID
  2. Install the Custom View
  3. Create a team (or utilize an existing one)
  4. Obtain the teamId from the Merchant Center URL
  5. Invite users to the team
  6. Assign relevant permissions to the team

After completing these steps, you will have an customViewId and a teamId. You must provide these values for env.production.customViewId and env.development.teamId, respectively, in the Custom View configuration file.

This process lets any member of the configured team log in and perform local development for the Custom View.