This topic describes how to troubleshoot issues that may occur when you install a custom plug-in. These issues include console-reported errors, cluster update suspension, and verification failures.

Problem description

When you upload and install a custom plug-in, issues occur, such as console-reported errors, cluster update suspension, and verification failures.

Common solutions

Before you upload and install a custom plug-in, you must place the plug-in in the plugins folder under the installation path of a self-managed Elasticsearch cluster. Then, restart the cluster to load the plug-in. After the cluster is restarted, run the GET /_cat/plugins?v command to check whether the plug-in is installed. When you install the plug-in, take note of the following items:
  • You cannot upload a plug-in that has the same name as a built-in plug-in provided by Alibaba Cloud Elasticsearch.
    If the plug-in that you want to upload has the same name as a built-in plug-in, you must change the name of the plug-in before you upload it. When you test the installation of a plug-in, such as pinyin analysis or IK analysis, on a self-managed Elasticsearch cluster, you must first delete the native plug-in that corresponds to the plug-in. Then, change the name of the plug-in that you want to install, and install the plug-in by running the following installation command that is used for a native plug-in. If the plug-in is installed, you can upload and install the plug-in to your Alibaba Cloud Elasticsearch cluster. 
    ./bin/elasticsearch-plugin install file:///path-to-your-plugins.zip
  • Custom plug-ins can be uploaded and installed to an Alibaba Cloud Elasticsearch cluster only after they are tested on a self-managed Elasticsearch cluster. These custom plug-ins are installed to the cluster by running the following installation command that is used for a native plug-in: 
    ./bin/elasticsearch-plugin install file:///path-to-your-plugins.zip
  • Rolling updates are unavailable for custom plug-ins.
  • You are not allowed to upload plug-ins whose security policies define add, delete, modify, and query permissions, such as the elasticsearch-analysis-hanlp plug-in.
  • Custom plug-ins cannot be installed for Logstash and Kibana. If you want to install a custom plug-in for Logstash or Kibana, you must first install the plug-in on a self-managed Elasticsearch cluster by running the installation command that is used for a native plug-in. After the plug-in is installed, submit a ticket to the technical support engineers of Alibaba Cloud Elasticsearch.
    Note After a plug-in that meets requirements is installed, you can query the logs of the plug-in on the Cluster Log tab of the Alibaba Cloud Elasticsearch console.

Console-reported errors

  • Cause

    The plug-in that you upload does not meet requirements.

  • Solution

    Modify the information of the plug-in. For more information, see Common solutions. For example, you can rename the plug-in or modify the configuration file of the plug-in.

Cluster update suspension

If the update of your cluster is suspended, you can perform the following operations to troubleshoot the issue:
  1. Check the size of the plug-in. Make sure that the size is less than 50 MB.

    If the size of the plug-in is greater than or equal to 50 MB, the plug-in is loaded at a low speed during the installation. In this case, you must terminate the loading and delete the plug-in. Then, modify the configuration of the plug-in. For example, you can delete some tokens provided by the plug-in. Make sure that the size of the plug-in is less than 50 MB before you upload and install the plug-in again.

  2. Check whether the system is writing data to data nodes.
    • Yes: Wait for a few minutes. The installation process is slow because the installation is performed during peak hours.
    • No: Terminate the installation. Then, delete the plug-in and test the availability of the plug-in again.

Verification failures

The following table describes the causes of verification failures and the solutions to these failures.

Issue Cause Solution
The Elasticsearch version specified for the plug-in is inconsistent with the version of your Alibaba Cloud Elasticsearch cluster. The Elasticsearch version specified for the plug-in is inconsistent with the version of your Alibaba Cloud Elasticsearch cluster. Modify the Elasticsearch version specified for the plug-in and package the plug-in again. For some plug-ins such as Jieba, you must make sure that the Elasticsearch version specified for the plug-in is consistent with the version of your Alibaba Cloud Elasticsearch cluster. For more information, see FAQ.
The plugin-descriptor.properties file of the plug-in cannot be found. The plugin-descriptor.properties file of the plug-in cannot be found after the plug-in package is decompressed. Check whether an excess level of directory is generated after the plug-in package is decompressed. For example, you can use WinRAR to decompress a package on your computer to the current folder. In this case, the file obtained after decompression is a JAR file, and the directory level of the JAR file is correct. If the JAR file is in another folder, the directory level of the JAR file is incorrect. In this case, you must package the JAR file again. For more information about the appropriate methods that can be used to package a JAR file, see the solution to the next issue.
The plug-in package is invalid. The plug-in is not packaged based on the related requirements. As a result, the obtained package is invalid.
Use an appropriate method to package the plug-in again. You can use one of the following methods to package a plug-in:
  • WinRAR: Right-click the JAR file that you want to package, select Add to archive, set the compression format to ZIP, and then specify the name of the package. The name must start with elasticsearch and include the Elasticsearch version specified for the plug-in, such as elasticsearch-analysis-ik-6.7.0.zip.
  • Zip: Run the zip -r command to package the desired file.
The plug-in has security issues. The security policy of the plug-in contains sensitive permission information. Test the installation of the plug-in on a self-managed Elasticsearch cluster before you install the plug-in on your Alibaba Cloud Elasticsearch cluster. For more information, see Common solutions.
Note After the issues described in the preceding table are resolved, you must place the plug-in package in the plugins folder and run the ./bin/elasticsearch-plugins install command to test the installation of the plug-in on a self-managed Elasticsearch cluster before you install the plug-in on your Alibaba Cloud Elasticsearch cluster. If the plug-in fails to be installed, you must test the availability of the plug-in again based on the error message that appears. You can upload and install the plug-in to your Alibaba Cloud Elasticsearch cluster only after the plug-in passes the availability test.