Troubleshooting OpenSearch Dashboards

Dashboards displays OpenSearch Dashboards server is not ready yet (an HTTP 503 not ready error) and doesn't finish loading. Dashboards shows this page whenever it hasn't finished starting up. A brief version is normal during a restart, upgrade, or blue/green deployment and clears on its own. Treat it as a problem when it persists. To narrow down the cause, check the domain's Cluster health and whether a configuration change or upgrade is in progress:

Dashboards reports "server is not ready yet" until all of its core services finish initializing, which is why a transient version of the message is expected during startup and blue/green deployments. When it persists with a green cluster, the most common cause is that the migration of the OpenSearch Dashboards index is blocked: on startup, Dashboards migrates its saved objects into a new index behind an alias, and if that migration can't complete, Dashboards never becomes ready. Common triggers for a blocked migration:

Keep your domain on a current service software version and take a snapshot before each upgrade. If you rely on Dashboards for production monitoring, consider the centralized Using OpenSearch UI in Amazon OpenSearch Service, which is not tied to a single domain's per-domain OpenSearch Dashboards index migration.

Dashboards fails to load and displays a message similar to the following:

Kibana must be able to specify the index within Elasticsearch multi-requests (rest.action.multi.allow_explicit_index=true).

The rest.action.multi.allow_explicit_index advanced cluster option is set to false. Set this option to true so that Dashboards can perform its bulk, mget, and msearch operations.

Set rest.action.multi.allow_explicit_index back to true in the domain's advanced options. This is a management-plane change you make with your own AWS credentials, either in the console (open the domain, choose Edit, and update Advanced cluster settings) or with the AWS Command Line Interface (AWS CLI):

aws opensearch update-domain-config \
  --domain-name my-domain \
  --advanced-options rest.action.multi.allow_explicit_index=true

Changing an advanced option triggers a blue/green deployment, so the change takes a few minutes to apply. For more information about advanced cluster settings, see Advanced cluster settings.

Don't set rest.action.multi.allow_explicit_index to false unless you intend to restrict index access through resource-based policies. Leaving it at the default (true) keeps Dashboards operational.

Dashboards restarts, crashes, or becomes unresponsive under load, especially when opening large dashboards or loading many saved objects.

The Dashboards process exhausted its available memory, often from loading too many saved objects or rendering heavy dashboards.

To catch this before Dashboards runs out of memory, watch the OpenSearchDashboardsHeapUtilization CloudWatch metric; if it consistently exceeds 80%, scale to a larger instance type. Right-size your instance type for your Dashboards usage, keep dashboards lean, and avoid raising savedObjects:listingLimit beyond what you need.

Certain Dashboards pages fail to load because the request payload exceeds the Dashboards payload limit (server.maxPayloadBytes, which defaults to 1 MB / 1,048,576 bytes).

Index patterns that match a very large number of indexes or fields produce requests larger than the payload limit.

Keep index patterns scoped to the indexes and fields you actually use so requests stay within the payload limit.

Dashboards is unavailable for most of the duration of an engine version-upgrade blue/green deployment. This is expected behavior, not a fault, and it resolves itself when the upgrade completes.

Dashboards stays offline for most of a version upgrade to avoid version-check race conditions between the old and new environments.

Wait for the upgrade to complete; Dashboards becomes available again automatically. Treat version upgrades as a planned Dashboards maintenance window and schedule them outside business-critical hours. For more information about configuration changes, see Making configuration changes in Amazon OpenSearch Service.

Schedule upgrades during low-traffic windows. If you need Dashboards availability that isn't tied to a single domain's upgrade window, consider the centralized Using OpenSearch UI in Amazon OpenSearch Service.

You start an engine version upgrade (or run the upgrade eligibility check) and it fails at the pre-upgrade check, before any upgrade begins. The validation notification lists one or more incompatible indexes, and can name the OpenSearch Dashboards index specifically. This typically happens when you upgrade to OpenSearch 3.x while the domain still has indexes created in OpenSearch 1.3, Elasticsearch 7.10, or earlier, including the OpenSearch Dashboards index. (Upgrades from OpenSearch 1.3 or 2.x must go to OpenSearch 2.19 first, then to OpenSearch 3.x.)

OpenSearch can read indexes only from the immediately preceding major version, so OpenSearch 3.x doesn't support indexes created in OpenSearch 1.3, Elasticsearch 7.10, or earlier. The pre-upgrade check blocks the upgrade and lists these indexes on purpose, so you don't lose any data. You must reindex or remove older indexes before a major version upgrade; the service doesn't reindex them automatically. The OpenSearch Dashboards index follows the same rule.

Reindex or retire old indexes so they don't span more than one major version; indexes left across several upgrades will eventually block one. Take a manual snapshot before every upgrade, and export your OpenSearch Dashboards saved objects periodically as a backup.

A single user or browser sees a blank page, blank reports, or a red banner that reads OpenSearch Dashboards did not load properly. Check the server output for more information., while other users are unaffected. Confirm by reproducing in a private (incognito) window or a different browser.

A stale browser cache causes this issue, especially after a service software update or when you use the Reporting feature.

Clear your browser cache after a service software update, and use a supported, up-to-date browser.