Common Extension Errors

This error guide documentation provides a list of common errors that users may encounter while creating an extension, along with a brief explanation of the error and possible solutions.

Steps to Check Extension Errors

To run the extension in debug mode, follow these steps:
1. To setupFDK method with debugging enabled, pass debug:true in the extension configuration. Refer to How to register for webhook events?
Verify the extension configuration that is passed in the setupFdk method.
Check the extension configuration on the Fynd Partners.

List of Errors while Creating an Extension

Invalid extension_cluster_url

EXTENSION_CLUSTER_URL="https://api.fynd.com"

Problem

We have different clusters available, such as fynd, fyndx5, fyndx1, jio, jiox0, jiox1, Tira, and Swadesh.
Before initializing an extension on a cluster, the extension's details are validated, and subsequent requests are made to that same cluster.
A valid cluster name is needed to validate these details so that all requests can be made to that cluster.
If a wrong cluster value is entered, for example, https://api.sit.fyndx1.de is entered instead of https://api.uat.fyndx1.de, the error message: Invalid api_key or api_secret will be displayed because the api_key and api_secret for the https://api.sit.fyndx1.de cluster is different from https://api.uat.fyndx1.de cluster.

Solution

Check the cluster value specified in the configuration file passed to the setupFdk() method.
Check if the cluster value specifies the correct protocol (that is, https://, http://, etc.) and ensure that it is correct.
These are some of the valid cluster names:

Invalid extension_api_key

EXTENSION_API_KEY="645f6dc97aa48d946e2e423a"

Problem

The error Invalid 'extension api_key' value typically occurs when an invalid or incorrect extension API key is used to authenticate and authorize requests made to an extension.
If the extension API key is invalid or incorrect, the extension’s OAuth will not be able to authenticate the request and will return an error message indicating that the API key value is invalid.
This error can occur due to various reasons such as an incorrect entry of the API key, or a mismatch between the API key and the extension cluster.

Solution

Make sure that you have entered the correct extension API key. Check for any typos, extra spaces, or missing characters in the API key.
Ensure that the API key is associated with the correct extension cluster. Ensure that the correct extension cluster has been entered correctly.

Invalid extension_api_secret

EXTENSION_API_SECRET="jG~qDNkjytUP8wE"

Problem

This error message typically occurs when the API secret provided by the user is incorrect.
Another reason for an invalid API secret error could be a mistake in entering the API secret, such as a typographical error, an extra space, or missing characters.

Solution

Check that the API secret has been entered correctly and that there are no typos or errors. Ensure that there are no extra spaces or missing characters in the API secret.
Update the extension library to the latest version, as the error may be caused by a bug or issue resolved in a newer version.
You can check the latest version of the extension library at fdk-extension-javascript.

Missing auth and uninstall callback

Problem

The uninstall callback in the extension is a function that is executed when the extension is uninstalled from the Fynd Commerce. This callback can be used to perform any necessary cleanup before the extension is removed, such as deleting data or resources associated with the extension.
The auth callback in the Fynd extension authenticates incoming requests to your extension. This callback is called before the extension is executed to verify the identity and permissions of the requester.

Solution

By defining and passing in auth and uninstall callback functions to the setupFdk method.

const fdk = require('@fynd/fdk');
const app = fdk();

app.setupFdk({
  callbacks: {
    auth: async function(req) {
      // Define your authentication logic here
    },
    uninstall: async function(req) {
      // Define your uninstall logic here
    }
  }
});

// Your function logic here

Invalid extension_base_url

let fdkExtension = setupFdk({
    api_key: "6220daa4a5414621b975a41f",
    api_secret: "EbeGBRC~Fthv5om",
    base_url: baseUrl, // this is optional
    scopes: ["company/product"], // this is optional
    callbacks: {
      auth: async function (req) {
        console.log("called auth callback");
      },

      uninstall: async function (req) {
        console.log("called uninstall callback");
      },
    },
});

Problem

This error occurs when extension base url is incorrect.
The extension base_url is misspelled or contains errors, has been deprecated or is no longer valid, is not properly formatted or does not adhere to the expected syntax or structure.

Solution

Verify that the extension base_url you are using is correct and valid. Check for any spelling or formatting errors, and make sure that the extension base_url is still recognized and supported by the extension.
Regenerate the base_url for the extension and update the launch url value in the Partner’s extension side.

Invalid ‘scopes’ in extension config

scopes: ["company/saleschannel", "company/application/settings"]

let fdkExtension = setupFdk({
    api_key: "6220daa4a5414621b975a41f",
    api_secret: "EbeGBRC~Fthv5om",
    base_url: baseUrl, // this is optional
    scopes: ["company/product"], // this is optional
    callbacks: {
      auth: async function (req) {
        console.log("called auth callback");
      },

      uninstall: async function (req) {
        console.log("called uninstall callback");
      },
    },
});

Problem

A set of permissions are required for an extension that is related to the data that will be accessed by the extension for the company in which it will be installed.
Fynd Commerce takes the user's consent to allow those permissions to be granted to the extension on behalf of the user when the extension is installed for a company.
This data is passed in the scopes parameter of the extension config to the setupFdk method.
The extension throws this error when the permissions set for the extension developer on the Fynd Partners do not match the permissions passed as a configuration in the setupFdk method.

Solution

Check if the scopes have a valid set of permissions and if they are a subset of the permissions set for that extension on the Fynd Partners.
Make sure that the permission set for the extension developer on the Fynd Partners matches the permission passed as a configuration in the setupFdk method.

Extension not initialized due to invalid data

Problem

When an extension is unable to initialize due to invalid data, it means that it cannot start up properly because the data being passed to it is either incorrect or incomplete.
This can happen for various reasons, such as missing or incomplete configuration settings, incorrect data formats, or unexpected data values.
When we want to run an extension, the details provided in the setupFdk() method are validated.
When the lower version of fdk-extension-javascript library is used in extension.

Solution

Check the values passed in the setupFdk function (api_key, api_secret, scope, webhook_config, cluster, storage, and callbacks).
Update the extension library to the latest version, as the error may be caused by a bug or issue resolved in a newer version.
Try uninstalling and reinstalling the extension, which may resolve the issue.

Invalid or missing ‘notification_email’

let fdkExtension = setupFdk({
    api_key: "6220daa4a5414621b975a41f",
    api_secret: "EbeGBRC~Fthv5om",
    base_url: baseUrl, // this is optional
    scopes: ["company/product"], // this is optional
    callbacks: {
      auth: async function (req) {
        console.log("called auth callback");
      },

      uninstall: async function (req) {
        console.log("called uninstall callback");
      },
    },
    storage: new RedisStorage(redis),
    access_mode: "offline",
    cluster: "https://api.fynd.com", // this is optional by default it points to prod.
    webhook_config: {
        api_path: "/webhook",
        notification_email: "test2@abc.com", // required
        subscribed_saleschannel: 'specific', //optional
        event_map: { // required
            'application/coupon/update': {
                version: '1',
                handler: handleCouponEdit
            }
        }
    }
});

Problem

The notification_email is typically used to specify an email address where notifications about the extension will be sent.
The notification_email value is passed to webhook_config object which is passed to setupFdk method.
If this field is missing or has an invalid value, the extension will create this error.

Solution

Ensure that the email address you have entered in the "notification_email" field is a valid and correctly formatted value, which should be passed to the "webhook_config" object in the "setupFdk" method.
Ensure that the email address you have entered can receive emails. Check to see if it is functional and if it is not, try another valid email address.

Invalid or missing ‘api_path’

let fdkExtension = setupFdk({
    api_key: "6220daa4a5414621b975a41f",
    api_secret: "EbeGBRC~Fthv5om",
    base_url: baseUrl, // this is optional
    scopes: ["company/product"], // this is optional
    callbacks: {
      auth: async function (req) {
        console.log("called auth callback");
      },

      uninstall: async function (req) {
        console.log("called uninstall callback");
      },
    },
    storage: new RedisStorage(redis),
    access_mode: "offline",
    cluster: "https://api.fynd.com", // this is optional by default it points to prod.
    webhook_config: {
        api_path: "/webhook",
        notification_email: "test2@abc.com", // required
        subscribed_saleschannel: 'specific', //optional
        event_map: { // required
            'application/coupon/update': {
                version: '1',
                handler: handleCouponEdit
            }
        }
    }
});

Problem

Fynd Commerce requires a path to call the webhooks to which the extension has subscribed. This path should be provided in the api_path parameter of the webhook configuration, which is passed in the setupFdk method.
If the api_path parameter is not included in the webhook_config that is passed in the webhook configuration for the setupFdk method.

Solution

Verify that the webhook_config object is passed in the extension configuration for the setupFdk method including the api_path parameter.
If you are still encounter the error, try uninstalling and reinstalling the extension, including the correct API path in the webhook_config object.

Invalid or missing ‘event_map’

let fdkExtension = setupFdk({
    api_key: "6220daa4a5414621b975a41f",
    api_secret: "EbeGBRC~Fthv5om",
    base_url: baseUrl, // this is optional
    scopes: ["company/product"], // this is optional
    callbacks: {
      auth: async function (req) {
        console.log("called auth callback");
      },

      uninstall: async function (req) {
        console.log("called uninstall callback");
      },
    },
    storage: new RedisStorage(redis),
    access_mode: "offline",
    cluster: "https://api.fynd.com", // this is optional by default it points to prod.
    webhook_config: {
        api_path: "/webhook",
        notification_email: "test2@abc.com", // required
        subscribed_saleschannel: 'specific', //optional
        event_map: { // required
            'application/coupon/update': {
                version: '1',
                handler: handleCouponEdit
            }
        }
    }
});

Problem

The error message "Invalid or missing event_map in webhook fynd extension" indicates that there is an issue with the configuration of a webhook of the extension for Fynd Platform.
If the event_map object is passed to the webhook_config object which is passed to setupFdk method.
If this setting is missing or invalid, the webhook extension will not be able to function properly.

Solution

Verify that the event_map setting is properly configured with the correct values. Ensure that the mapping of Fynd events to webhook URLs is correct and that there are no errors in the configuration.
Test the webhook extension by triggering a event that should trigger the webhook. Check that the webhook receives the event and that the expected action is performed.
Please refer this link to know more about webhook : https://platform.fynd.com/help/docs/company-settings/webhook/

Webhook registry not initialized

Problem

A webhook registry is a mechanism that allows you to store and manage webhooks for your Fynd account.
This error message indicates that the webhook registry has not been properly initialized, which could prevent the webhook extension from functioning properly.

Solution

Check that the webhook registry has been properly set up and that all required fields have been filled in.
Check that the webhook registry has been initialized properly before attempting to use it.

Failed to sync webhook events. Reason ${reason}

Problem

There is an issue with syncing events to a webhook, and that the reason for the failure is related to a specific cause.
It is possible that the webhook URL is incorrect, the webhook server is down, the api_secret is incorrect, or the notification_email is incorrect.

Solution

Ensure that the URL for the webhook is correct .
Ensure that the api_secret and notification email for the subscriberConfig object are passed correctly.
Ensure that the status, auth_meta, association, and event_id are passed correctly to the subscriberConfig object.

Failed to add saleschannel webhook. Reason: ${reason}

Problem

There was an issue when attempting to add a sales channel webhook in the Fynd extension, and that there is a specific reason for the failure.
The Fynd extension is a tool that allows you to integrate your online store with the Fynd platform. This integration enables you to synchronize your store's inventory, orders, and other data with Fynd, helping you in managing your business more efficiently.
One of the features of the Fynd extension is the ability to create sales channel webhooks.

Solution

Ensure that the URL for the webhook is correct .
Ensure that the sales channel configuration is correctly set up and matches the configuration of the webhook. If the sales channel configuration is incorrect, it may prevent the webhook from being removed successfully.
Verify that the api_secret, notification_email, status, auth_meta, association and event_id are correctly passed to the subscriberConfig object.

Signature passed does not match calculated body signature

verifySignature(req) {
        const reqSignature = req.headers['x-fp-signature'];
        const { body } = req;
        const calcSignature = hmacSHA256(JSON.stringify(body), this._fdkConfig.api_secret).toString();
        if (reqSignature !== calcSignature) {
            throw new FdkInvalidHMacError(`Signature passed does not match calculated body signature`);
        }
  }

Problem

There is an issue with the signature verification process for a webhook. When you create a webhook, the sales channel sends a signature with each webhook request to verify that the request is legitimate.
The Fynd extension calculates its own signature based on the request body and compares it to the signature passed by the sales channel. If the two signatures do not match, this error is thrown.

Solution

Please ensure that the webhook is configured correctly in the sales channel and in the Fynd extension. Verify that the webhook URL, secret key, and other settings match.
Make sure that the Fynd extension is using the correct method to calculate the signature. Different sales channels may use different algorithms to calculate signatures, so it's important to ensure that the Fynd extension is using the same method as the sales channel.

Invalid client : client is invalid

Problem

The error message "Invalid client: client is invalid" in OAuth indicates that the client attempting to authenticate itself is not recognized by the authorization server or its credentials are incorrect.
This error can occur due to a variety of reasons, such as incorrect client ID or client secret, expired or revoked client credentials, or misconfigured authorization server settings.

Solution

To troubleshoot this issue, you should check that the extension’s client ID and client secret are correctly entered and match the values configured in the authorization server.
Additionally, ensure that the client credentials are still valid and have not expired or been revoked.

Webhook handler not assigned ${categoryEventName}

Problem

The "webhookhandler not assigned" error typically occurs when there is an attempt to trigger a webhook, but the webhook handler function has not been properly assigned or defined in the setupFdk method.
A webhook handler is a function that receives and processes the data sent by a webhook notification.
When a webhook event is triggered, the webhook service sends payloads to corresponding server.

Solution

To resolve this error, ensure that the webhook handler function is properly defined.
Ensure that application_id and company_id are correctly passed to the extHandler method.

Failed to remove saleschannel webhook. Reason: ${reason}

Problem

There was an issue when attempting to remove a sales channel webhook in the Fynd extension, and that there is a specific reason for the failure.
One of the features of the Fynd extension is the ability to remove sales channel webhooks.
When you remove a sales channel webhook, you are effectively telling the sales channel to stop sending these updates to your store.
The reason for the failure could be related to any number of issues, such as an incorrect webhook URL, api_secret, event_configs or an issue with the sales channel configuration.

Solution

Ensure that the URL for the webhook is correct .
Ensure that the sales channel configuration is correctly set up and matches the configuration of the webhook. If the sales channel configuration is incorrect, it may prevent the webhook from being removed successfully.
Verify that the api_secret, notification_email, status, auth_meta, association and event_id are correctly passed to the subscriberConfig object.

Error while fetching webhook subscriber configuration, Reason: ${reason}

Problem

There is an error with fetching the webhook subscriber configuration.
The reason for the failure could be related to any number of issues, such as an incorrect webhook URL or api_key.

Solution

Ensure that the URL for the webhook is correct .
Verify that the api_key are correctly passed to the subscriberConfig object.

Error while fetching webhook events configuration, Reason: ${reason}

Problem

There was a problem while trying to retrieve the events configuration for a webhook. If an invalid URL, data, or headers object is passed to the rawRequest object, it may result in an error. This error can also occur if the headers object has been incorrectly configured, specifically if the Content-Type is not set correctly.

Solution

It is important to ensure that the URL, data, and headers objects are properly formatted and structured to avoid encountering this error when using the rawRequest object.
Verify that the Content-Type are correctly passed to the headers object.

Eror 404: Not Found

Problem

When an extension is accessed on a platform or application, all requests are directed to the extension's base URL, which is specified in the extension details on the Partners Panel. One reason for receiving this error is that the extension's Launch URL is not accessible.

Solution

Check if your extension server is running.
You can run the extension in debug mode.
To resolve this error, it is recommended to check if the Launch URL specified in the extension details on the Partners Panel is correct.

Invalid or expired token while using FDK-CLI to create an extension

Problem

An invalid or expired token is an error message you may encounter when trying to access an extension that requires authentication or authorization.
An expired token means that the token has reached its validity period and can no longer be used to access the resource.
An invalid token means that the token is not recognized or has been revoked.

Solution

You will need to obtain a new token to continue accessing the extension.
This may involve logging in again or requesting a new token from the Partners panel.
The CLI command used to create an extension using FDK-CLI is fdk extension init —host api.fyndx1.de.

Steps to Check Extension Errors​

List of Errors while Creating an Extension​

Steps to Check Extension Errors

List of Errors while Creating an Extension