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.

Here are some common steps to check for extension errors:

1. To run the extension in debug mode, follow these steps:
   1. To setupFdk method with debugging enabled, pass “debug:true” in the extension configuration.
   2. For an example, please refer to link.
2. Verify the extension configuration that is passed in the setupFdk method.
3. Check the extension configuration on the Partners Panel.

List of errors while creating an extension

• Invalid extension_cluster_url
• Invalid extension_api_key
• Invalid extension_api_secret
• Missing auth and uninstall callback
• Invalid extension_base_url
• Invalid scopes in extension config
• Extension not initialised due to invalid data
• Invalid or missing notification_email
• Invalid or missing api_path
• Invalid or missing event_map
• Webhook registry not initialised
• Failed to sync webhook events. Reason: ${reason}
• Failed to add saleschannel webhook. Reason: ${reason}
• Signature passed does not match calculated body signature
• Invalid client: client is invalid
• Webhook handler not assigned ${categoryEventName}
• Failed to remove saleschannel webhook. Reason: ${reason}
• Error while fetching webhook subscriber configuration, Reason: ${reason}
• Error while fetching webhook events configuration, Reason: ${reason}
• 404 Not Found Error
• Invalid or expired token while using fdk-cli to create an extension

1. Invalid extension_cluster_url

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

Problem:

1. We have different clusters available, such as fynd, fyndx5, fyndx1, jio, jiox0, jiox1, Tira, and Swadesh.
2. Before initializing an extension on a cluster, the extension's details are validated, and subsequent requests are made to that same cluster.
3. A valid cluster name is needed to validate these details so that all requests can be made to that cluster.
4. For example, if a wrong cluster value, such as "https://api.sit.fyndx1.de" instead of "https://api.uat.fyndx1.de", is entered, 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 are different from the api_key and api_secret for the "https://api.uat.fyndx1.de" cluster.

Solution:

1. Check the cluster value specified in the configuration file that is passed to the setupFdk() method.
2. Check if the cluster value specifies the correct protocol (i.e., "https://", "http://", etc.) and ensure that it is correct.
3. These are some of the valid cluster names:
   1. https://api.fynd.com
   2. https://api.uat.fyndx1.de
   3. https://api.sit.fyndx1.de
   4. https://api.jio.com
   5. https://api.tira.com

2. Invalid extension_api_key

EXTENSION_API_KEY="645f6dc97aa48d946e2e423a"

Problem:

1. The error "Invalid 'extension api_key' value" typically occurs when an extension API key that is invalid or incorrect is used to authenticate and authorize requests made to an extension.
2. 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.
3. 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:

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

3. Invalid extension_api_secret

EXTENSION_API_SECRET="jG~qDNkjytUP8wE"

Problem:

1. An "invalid API secret" error message typically occurs when the API secret provided by the user is incorrect.
2. 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:

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

4. Missing auth and uninstall callback

Problem:

1. The uninstall callback in the extension is a function that is executed when the extension is uninstalled from the Fynd platform. 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.
2. The auth callback in the Fynd extension is used to authenticate incoming requests to your extension. This callback is called before the extension is executed to verify the identity and permissions of the requester.

Solution:

1. 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

5. Invalid ‘extension_base_url’

EXTENSION_BASE_URL="https://0d9b-103-240-162-120.ngrok-free.app"

Problem:

1. In general, an "invalid extension base_url" error could indicate that the extension base_url provided is incorrect.
2. 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:

1. 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.
2. Regenerate the base_url for the extension and update the launch url value in the Partner’s extension side.

6. Invalid ‘scopes’ in extension config

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

Problem:

1. A set of permissions is 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.
2. Fynd platform 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.
3. This data is passed in the scopes parameter of the extension config to the setupFdk method.
4. The extension throws this error when the permissions set for the extension developer on the partners panel do not match the permissions passed as a configuration in the setupFdk method.

Solution:

1. 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 partners panel.
2. Make sure that the permission set for the extension developer on the partners panel match the permission passed as a configuration in the setupFdk method.

7. Extension not initialized due to invalid data

Problem:

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

Solution:

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

8. 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: "[email protected]", // required
        subscribed_saleschannel: 'specific', //optional
        event_map: { // required
            'application/coupon/update': {
                version: '1',
                handler: handleCouponEdit
            }
        }
    }
});

Problem:

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

Solution:

1. 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.
2. Ensure that the email address you have entered is able to receive emails. Check to see if the email address is functional and if it is not, try another valid email address.

9. Invalid or missing ‘api_path’

Problem:

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

Solution:

1. Verify that the webhook_config object that is passed in the extension configuration for the setupFdk method includes the api_path parameter.
2. If you are still encountering the error, try uninstalling and reinstalling the extension, making sure to include the correct API path in the webhook_config object.

10. Invalid or missing ‘event_map’

Problem:

1. 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.
2. If the event_map object is passed to the webhook_config object which is passed to setupFdk method.
3. If this setting is missing or invalid, the webhook extension will not be able to function properly.

Solution:

1. 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.
2. 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.
3. Please refer this link to know more about webhook : https://platform.fynd.com/help/docs/company-settings/webhook/

11. Webhook registry not initialized

Problem:

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

Solution:

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

12. Failed to sync webhook events. Reason ${reason}

Problem:

1. There is an issue with syncing events to a webhook, and that the reason for the failure is related to a specific cause.
2. 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:

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

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

Problem:

1. 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.
2. 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.
3. One of the features of the Fynd extension is the ability to create sales channel webhooks.

Solution:

1. Ensure that the URL for the webhook is correct .
2. 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.
3. Verify that the api_secret, notification_email, status, auth_meta, association and event_id are correctly passed to the subscriberConfig object.

14. 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:

1. 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.
2. 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:

1. 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.
2. 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.

15. Invalid client : client is invalid

Problem:

1. 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.
2. 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:

1. 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.
2. Additionally, ensure that the client credentials are still valid and have not expired or been revoked.

16. Webhook handler not assigned ${categoryEventName}

Problem:

1. 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.
2. A webhook handler is a function that receives and processes the data sent by a webhook notification.
3. When a webhook event is triggered, the webhook service sends payloads to corresponding server.

Solution:

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

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

Problem:

1. 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.
2. One of the features of the Fynd extension is the ability to remove sales channel webhooks.
3. When you remove a sales channel webhook, you are effectively telling the sales channel to stop sending these updates to your store.
4. 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:

1. Ensure that the URL for the webhook is correct .
2. 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.
3. Verify that the api_secret, notification_email, status, auth_meta, association and event_id are correctly passed to the subscriberConfig object.

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

Problem:

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

Solution:

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

19. 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:

1. 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.
2. Verify that the Content-Type are correctly passed to the headers object.

20. 404 Not Found Error

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:

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

21. Invalid or expired token while using fdk-cli to create an extension

Problem:

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

Solution:

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