Troubleshoot custom plug-in installation issues - Elasticsearch

Custom plug-in installation on Alibaba Cloud Elasticsearch can fail with console-reported errors, cluster update suspension, or verification failures. This topic helps you identify the cause and resolve each type of failure.

Before you install

Review these constraints before uploading a custom plug-in. Violating them is the most common cause of installation failure.

Size limit: The plug-in package must be less than 50 MB. Larger packages load slowly and cause cluster update suspension.
No duplicate names: A custom plug-in cannot share a name with a built-in Alibaba Cloud Elasticsearch plug-in. Rename the plug-in before uploading.
Test on a self-managed cluster first: Every custom plug-in must pass a local installation test before you upload it to Alibaba Cloud Elasticsearch. Use the following command to test:
```
./bin/elasticsearch-plugin install file:///path-to-your-plugins.zip
```
Place the plug-in package in the plugins directory under the installation path of your self-managed Elasticsearch cluster, restart the cluster, then run the following command to confirm the plug-in loaded:
```
GET /_cat/plugins?v
```
No rolling updates: Rolling updates are not available for custom plug-ins.
Security policy restrictions: Plug-ins whose security policies define add, delete, modify, and query permissions (for example, elasticsearch-analysis-hanlp) cannot be uploaded.
Logstash and Kibana: Custom plug-ins cannot be installed directly for Logstash or Kibana. Test the plug-in on a self-managed cluster using the native installation command, then submit a ticket to Alibaba Cloud Elasticsearch technical support.

After a plug-in is successfully installed, view its logs on the Cluster Log tab of the Alibaba Cloud Elasticsearch console.

Console-reported errors

Cause: The plug-in does not meet requirements.

Fix: Check the constraints in Before you install. Common actions include renaming the plug-in or modifying its configuration file to remove disallowed permissions.

Cluster update suspension

If cluster update is suspended after you install a plug-in, check the following:

Check the plug-in size. If the package is 50 MB or larger, stop the installation, delete the plug-in, and reduce its size (for example, by removing unnecessary token dictionaries) until it is under 50 MB. Then re-upload and install.
Check whether the cluster is writing data. Run a query to see if data nodes are active.
- Yes, data is being written: Wait a few minutes. Installation is slow during peak hours and will complete on its own.
- No data is being written: Stop the installation, delete the plug-in, and test it again on a self-managed cluster before re-uploading.

Verification failures

The following table lists common verification errors, their causes, and fixes.

Error	Cause	Fix
Elasticsearch version mismatch	The Elasticsearch version in the plug-in descriptor does not match the version of your Alibaba Cloud Elasticsearch cluster.	Update the version in the plug-in descriptor to match your cluster version exactly (for example, `7.10.1`). For plug-ins such as Jieba, the version must match down to the patch level. Then repackage. For more information, see FAQ.
`plugin-descriptor.properties` not found	The descriptor file is missing from the decompressed package, usually because an extra directory level was created during packaging.	Decompress the package locally and check the directory structure. Check whether an excess level of directory is generated after decompression. The JAR file must be at the correct directory level, not nested inside an extra folder. If the structure is incorrect, repackage the plug-in.
Invalid plug-in package	The plug-in was not packaged correctly. Elasticsearch expects binaries, not source code.	Repackage using one of the following methods: WinRAR: Right-click the JAR file, select Add to archive, set the format to ZIP, and name the archive starting with `elasticsearch` followed by the version (for example, `elasticsearch-analysis-ik-6.7.0.zip`). Command line: Run `zip -r` to package the desired file.
Security issues	The plug-in's security policy contains sensitive permissions.	Test the plug-in on a self-managed Elasticsearch cluster first. See Before you install for the test procedure.

After resolving any of the above errors, place the plug-in package in the plugins directory and run the following command to re-test on your self-managed cluster:

./bin/elasticsearch-plugins install

Upload the plug-in to Alibaba Cloud Elasticsearch only after it passes this local availability test. If the test fails, check the error message and repeat the steps above.