Elasticsearch:Common errors

Cause

This error occurs when you use the LIKE operator in an X-Pack SQL plug-in query against a text type field.

Solution

The LIKE operator only supports exact filtering on keyword type fields. Switch the query to use a keyword field instead.

For background, see Unable to run SQL query on multi fields using Elastic Search v. 7.3 and SQL and multi-fields.

Cause

When a field is mapped as keyword, Elasticsearch does not automatically create a .keyword subfield. A wildcard query statement against a nonexistent subfield, such as titleForSearch.keyword, returns no results.

Solution

Update the query statement to run the wildcard or regexp query against the parent field. For example:

{
  "query": {
    "wildcard": {
      "titleForSearch": "*keyword*"
    }
  }
}

Optimization suggestions

• If you need analyzed full-text search, reindex the data and explicitly map the field as text with the IK tokenizer.

• If you retain the keyword type, query the parent field and remove the unnecessary .keyword suffix.

• Explicitly define the mapping in your application code to avoid differences caused by the dynamic mapping strategy.

Cause

Elasticsearch supports the keyword type only in lowercase. Using uppercase KEYWORD in a mapping causes the No handler for type [KEYWORD] error.

Solution

Change the affected field type from "KEYWORD" to "keyword", and then submit the mapping again.

Additional troubleshooting

If the mapping is correct but the error persists, check whether a newly added field in the source database causes a synchronization task, such as a DataWorks task, to perform automatic creation of a mapping with an invalid type. Verify the field definitions in the application code or the synchronization tool.

Cause

This error appears when you use the aliyun-knn plug-in for vector search on an index configured with the cosine distance measurement function.

Solutions

Check the following:

• Cluster version: The aliyun-knn plug-in requires Elasticsearch V6.7 with kernel V1.2 or later, or Elasticsearch V7.10 with kernel V1.4 or later. See Use the aliyun-knn plug-in for version requirements.

• Script query method: Script queries must use the script_score parameter.

• Field nesting: Verify that the fields specified in the query match the nesting structure of the index mapping. If the index uses nested fields, the query must reference nested fields accordingly.

Cause

A single bulk write request exceeds the http.max_content_length limit, which defaults to 100 MB. Do not change this limit.

Solution

Data written per request equals the number of documents multiplied by the average document size. Because document size varies, start tuning at 5 MB per request and work up to a maximum of 15 MB. For guidance, see Using and Sizing Bulk Requests and HTTP settings.

Cause

Auto Indexing is disabled on the cluster.

Solutions

• Static method (recommended): Enable Auto Indexing in the YML File Configuration panel. For steps, see Configure the YML file.

• Dynamic method: Run the corresponding API command to enable Auto Indexing without restarting the cluster.

Error description

This error appears when the cluster cannot serve queries from one or more shards.

Causes

Common causes include node disconnection, shards still recovering after a restart, or a damaged disk.

Solution

Step 1: Diagnose

Check the cluster's monitoring data and logs to identify the root cause — for example, insufficient disk space or misconfigured index or cluster settings that block shard allocation.

Step 2: Fix unassigned shards

If node disconnection or unassigned shards are the cause:

1. Log in to the Kibana console.

2. Check the shard allocation status:

   Note

   If all shards are already allocated, this command returns an error — that is expected behavior.

   GET /_cluster/allocation/explain

3. Retry failed shard allocation:

POST /_cluster/reroute?retry_failed=true

Cause

When disk usage on a data node exceeds 95%, Elasticsearch triggers write protection and sets read_only_allow_delete on all indexes. Writes are blocked; only reads and deletes are allowed. The 85% threshold affects shard creation, and the 95% threshold triggers write protection.

Solution

Step 1: Resolve high disk usage (root cause)

Address the underlying disk usage first. See High disk usage and read-only indexes for options such as expanding disk capacity, deleting unused indexes, or configuring index lifecycle management.

Step 2: Restore write access

After resolving disk usage, reset the read-only flag across all indexes:

PUT _settings
{
   "index.blocks.read_only_allow_delete": null
}

Cause

The cluster logs show an SSL/TLS error similar to the following when plaintext traffic is sent over an SSL connection. This typically happens when a node without encrypted communication tries to connect to a node that has encryption enabled.

content :
[o.e.t.TcpTransport ] [XBJo5pR] exception caught on transport layer [Netty4TcpChannel{localAddress=0.0.0.0/0.0.0.0:9300, remoteAddress=/89.248.xxx}], closing connection
io.netty.handler.codec.DecoderException: io.netty.handler.ssl.NotSslRecordException: not an SSL/TLS record: 0300002f2axxxx8
61736xxx a0100080003000000

Solutions

Check the following:

• HTTP vs. HTTPS mismatch: If HTTPS is not enabled on the cluster, access is only available over HTTP. Accessing the cluster over HTTPS triggers this error. To enable HTTPS, see Enable HTTPS.

• IP address not allowlisted: Verify that the IP address shown in the cluster logs is in the public IP address whitelist. Add only the specific IP addresses or CIDR blocks you need — do not add 0.0.0.0/0.

For more SSL/TLS error patterns, see Common SSL/TLS exceptions.

Cause

The cluster does not have API key authentication enabled.

Solution

API keys require HTTPS to be active on the cluster. Enable HTTPS to resolve this. See Enable HTTPS.

Error description

When using Transport Client 5.5 or 5.6 to connect over port 9300, you may see:

NoNodeAvailableException[None of the configured nodes are available: [{#transport#-1}{HVdK7Cffxxxx_P0c9nxxxx}{es-cn-v1qqweee****.elasticsearch.aliyuncs.com}{172.17.XX.XX:9300}]]

Solution

The 172.17.XX.XX IP address is not an actual node in the cluster — this is a known issue with those client versions. Use Transport Client 5.3.3 instead. See Transport Client (5.x).

Error description

After enabling throttling with apack.qos.ratelimit.enabled, you see this error when configuring a limiter:

{
   "error": {
      "root_cause": [
         {
            "type": "unsupported_operation_exception",
            "reason": "unsupported_operation_exception: only define search or bulk action for limit"
         }
      ],
      "type": "unsupported_operation_exception",
      "reason": "unsupported_operation_exception: only define search or bulk action for limit"
   },
   "status": 500
}

Cause

The aliyun-qos plug-in is not at the latest version. Run GET /_cat/plugins?v to check the current version. The expected latest versions are:

• Elasticsearch V7.10:7.10.0_ali1.6.0.2

• All other versions:<ES version>-rc4

Solutions

Upgrade based on your cluster version:

• V7.10 clusters: Upgrade the kernel to V1.6.0. See Upgrade the version of a cluster.

• Other versions:Submit a ticket to have Elasticsearch technical engineers upgrade the plug-in. Restart the cluster after the upgrade for the change to take effect.

Cause

These errors are caused by bugs in open source Elasticsearch 7.4 and do not affect your business operations. The bugs are fixed in versions later than 7.4.

Solution

Alibaba Cloud Elasticsearch V7.4 is phased out. Purchase a cluster running a later version. If you need to migrate data before switching, see Select a data migration solution to choose the right approach for your workload.

Cause

This error occurs when running PUT _snapshot/my_backup if the target Object Storage Service (OSS) bucket uses the Archive storage class. Archive buckets require object restoration before data can be read, which is incompatible with Elasticsearch snapshot operations.

Solution

Use a Standard storage class OSS bucket in the same region as the Elasticsearch cluster. For steps, see Create manual snapshots and restore data from manual snapshots.