Skip to main content
search
Error Logs

Error Log: “timed_out: true” – The slow query

By November 19, 2025No Comments

Error Log: You don’t see this in the OpenSearch logs; you see it in the response to your search query. The query returns partial results, and the JSON contains this key:

JSON

{
  "took" : 30005, // <-- Time taken, just over the default 30s
  "timed_out" : true, // <-- The key indicator
  "_shards" : {
    "total" : 10,
    "successful" : 9, // <-- Notice not all shards finished
    "skipped" : 0,
    "failed" : 1      // <-- One or more shards timed out
  },
  "hits" : {
    // ... partial results
  }
}

Why… is this happening? This means your search query took longer than the allowed timeout (which defaults to 30 seconds). OpenSearch didn’t fail; it simply stopped the query where it was and returned whatever results it had gathered so far.

This is a symptom of a slow query, which can be caused by:

  1. An Expensive Query: You are running a very complex query. Common culprits include:
    • Deep or high-cardinality terms aggregations.
    • Wildcard queries, especially with a leading wildcard (e.g., *error).
    • Complex bool queries with many clauses.
    • Using scripts (script_score, script_fields).
  2. Too Much Data: Your query is scanning too many indices or too large a time range.
  3. Overloaded Cluster: Your cluster is busy with other tasks (like heavy indexing or other slow searches) and doesn’t have enough CPU, memory, or I/O to finish your query in time.
  4. Unoptimized Mappings: You are searching on analyzed text fields for things that should be on keyword fields.

Best Practice:

  1. DO NOT Just Increase the Timeout: While you can add ?timeout=60s to your query, this is a bad idea. It just makes your application wait longer and puts more stress on the cluster. The real fix is to optimize the query.
  2. Use the Profile API: This is your best tool. Run your query again, but add "profile": true to the top level of your query JSON. The response will give you a detailed breakdown of exactly where OpenSearch is spending its time (e.g., building aggregations, fetching data).
  3. Filter Your Time Range: The most effective optimization. Always filter on a time-based field (like @timestamp) to the smallest possible range.
  4. Optimize Your Query Logic:
    • Avoid leading wildcards.
    • Filter before you aggregate.
    • For deep pagination, use the search_after parameter, not a large from size.

What else can I do? Struggling to read the Profile API output or still can’t get your query to speed up? Share your query and your index mapping on the OpenSearch community forums. For direct help with performance tuning, contact us in The OpenSearch Slack Channel in #General.

Author