Error log: “Courier fetch: XXX of YYY shards failed” – The dashboard search failure

Error log: This error appears in the OpenSearch Dashboards UI (in your browser) when you try to load a dashboard, run a Discover query, or use a visualization.

Courier fetch: 10 of 20 shards failed.

The following shards had errors:

• index: my-logs-2025.11.03, shard: 0, reason: search_phase_execution_exception
• …

Why… is this happening? “Courier” is the name of the data-fetching module used by OpenSearch Dashboards. This error is a user-friendly wrapper for a backend OpenSearch query failure.

It means Dashboards sent a search query to OpenSearch, and one or more shards failed to execute that query. It’s the UI equivalent of the "all shards failed" or "search_phase_execution_exception" errors we’ve covered before.

The real error is in the reason provided for each shard. Common reasons you’ll see here include:

• illegal_argument_exception: The most common cause. A visualization is trying to aggregate on a text field instead of a .keyword field.
• circuit_breaking_exception: The query (often a complex aggregation) was too large and would have used too much memory, so the circuit breaker stopped it.
• search_phase_execution_exception: A generic error; you’ll have to check the OpenSearch logs for the real root cause.
• parsing_exception: The query generated by Dashboards is invalid, which can happen if a saved query or filter is corrupted.

Best Practice:

1. Inspect the Shard Errors: Don’t dismiss the popup! Read the reason for the failed shards.
2. Fix Mappings (for illegal_argument_exception): If the error mentions aggregating on a text field, you must edit the visualization (in the “Visualize” library) or the saved search (in “Discover”) to use the .keyword version of that field.
3. Optimize Visualizations (for circuit_breaking_exception): Your dashboard is trying to do too much.
   • Add more filters to the dashboard to reduce the amount of data being queried.
   • Reduce the size of terms aggregations in your visualizations.
   • Shorten the time range of your query.
4. Use Dev Tools: Copy the query that failed (you can often get this from the “Inspect” menu on a visualization) and run it directly in Dev Tools. This will give you the full, detailed JSON error response, which is much more helpful than the “Courier fetch” summary.

What else can I do? If you can’t figure out why a specific visualization is failing, the OpenSearch community can help. Post a screenshot of your visualization’s configuration and the error message. For direct support, you can also contact us in The OpenSearch Slack Channel in #General.