Error log: “all shards failed” – The misleading error

Error log: When you run a search query, you might get a JSON response like this, or a similar exception in your application logs:
JSON

{
  "error" : {
    "root_cause" : [
      {
        "type" : "query_shard_exception",
        "reason" : "No mapping found for [field_name] in order to sort on",
        "index_uuid" : "...",
        "index" : "my-index-001"
      }
    ],
    "type" : "search_phase_execution_exception",
    "reason" : "all shards failed", // <-- The high-level error
    "phase" : "query",
    "grouped" : true,
    "failed_shards" : [
      // ... details of the real error
    ]
  },
  "status" : 400
}

Why… is this happening? The "all shards failed" message is a wrapper exception. It doesn’t tell you the real problem. It only tells you that the query you sent failed to execute successfully on every shard it was sent to.
The actual error is always found inside the "root_cause" section of the JSON response. In the example above, the real problem is No mapping found for [field_name] in order to sort on.

Common root causes include:

• Query syntax error: A typo in your Query DSL.
• Mapping mismatch: Trying to sort or aggregate on a text field instead of a .keyword field.
• Scripting error: An error in a painless script used in your query.
• Fielddata error: Trying to sort on a text field without fielddata=true enabled (which is discouraged).

Best Practice:

1. Always read the root_cause: Ignore the “all shards failed” message and immediately look for the root_cause array in the JSON error response. This will give you the true reason for the failure.
2. Check server logs: If the root_cause is still vague, check the logs on your OpenSearch data nodes (in the logs/opensearch.log file) at the time of the query. They will contain the full, detailed stack trace.
3. Validate your query: Before running a complex query in your application, test it in the OpenSearch Dashboards Dev Tools to get immediate, clear feedback on syntax errors.

What else can I do? Stuck on a query that keeps failing, even after checking the root cause? The OpenSearch community forums are a great place to post your query and mapping. You can also contact us directly for assistance at help@opensearchsoftwarefoundation.org.