[Metrics][Discover] Refactor METRICS_INFO error handling (#270627)

Closes #260667

## Summary

Aligns Metrics in Discover `METRICS_INFO` failures with main Discover
search errors by replacing the custom `MetricsInfoError` component with
Discover’s shared `ErrorCallout` (via a `ChartSectionSearchError`
wrapper).

ES|QL error handling is centralized under `src/common/errors/` so
Metrics and Traces can reuse the same path, including HTTP 200 responses
with an embedded Elasticsearch error body. Discover injects
`showErrorDialog` and `esqlReferenceHref` from the metrics profile
wrapper—the same pattern as `discover_layout.tsx` after
[#261332](#261332).


### Changes

- **Error handling**
- Moved `esql_response_error` to `src/common/errors/` and improve
`formatErrorCause` (all `root_cause` entries, `caused_by` fallback)
  - Added `normalizeChartSectionSearchError`
- Update `execute_esql_query` and `report_chart_section_error` imports
to the shared module
- **UI**
- Added `ChartSectionSearchError` wrapping `@kbn/discover-utils`
`ErrorCallout`
- Metrics Experience Grid now render `ChartSectionSearchError` on `|
METRICS_INFO` failure
  - Removed `metrics_info_error.tsx`
- **Discover host wiring**
- `chart_section.tsx` passes `chartSectionSearchError` with
`core.notifications.showErrorDialog` and
`docLinks.links.query.queryESQL` (same behaviour as main Discover
`ErrorCallout`)
- Added `ChartSectionSearchErrorHostProps` to `UnifiedMetricsGridProps`
- **i18n**
  - Remove unused `metricsExperience.metricsInfoError.*` keys
  - Add `metricsExperience.chartSectionError.title`

### Expected Results

We're now able to see Discover's error component on a METRICS_INFO call
error (Error description is custom for the demonstration)
<img width="1584" height="709" alt="image"
src="https://github.com/user-attachments/assets/81b7f380-8b07-4d36-b732-de7742c661f7"
/>

---------

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>

Author: jorgeoliveira117

…/chart/utils/esql_response_error.test.ts …ommon/errors/esql_response_error.test.tssrc/platform/packages/shared/kbn-unified-chart-section-viewer/src/components/chart/utils/esql_response_error.test.ts renamed to src/platform/packages/shared/kbn-unified-chart-section-viewer/src/common/errors/esql_response_error.test.ts src/platform/packages/shared/kbn-unified-chart-section-viewer/src/components/chart/utils/esql_response_error.test.ts renamed to src/platform/packages/shared/kbn-unified-chart-section-viewer/src/common/errors/esql_response_error.test.ts

@@ -12,6 +12,7 @@ import {
   EsqlResponseError,
   extractEsqlEmbeddedError,
   formatErrorCause,
+  isEsqlResponseError,
 } from './esql_response_error';
 
 describe('formatErrorCause', () => {
@@ -32,6 +33,27 @@ describe('formatErrorCause', () => {
     ).toBe('index_not_found_exception: no such index [metrics-*]');
   });
 
+  it('joins multiple root_cause entries with newlines', () => {
+    expect(
+      formatErrorCause({
+        root_cause: [
+          { type: 'index_not_found_exception', reason: 'no such index [cluster-a:metrics-*]' },
+          { type: 'index_not_found_exception', reason: 'no such index [cluster-b:metrics-*]' },
+        ],
+      })
+    ).toBe(
+      'index_not_found_exception: no such index [cluster-a:metrics-*]\nindex_not_found_exception: no such index [cluster-b:metrics-*]'
+    );
+  });
+
+  it('returns message from caused_by when type, reason, and root_cause are missing', () => {
+    expect(
+      formatErrorCause({
+        caused_by: { type: 'illegal_argument_exception', reason: 'invalid query' },
+      })
+    ).toBe('illegal_argument_exception: invalid query');
+  });
+
   it('returns generic message for empty error object', () => {
     expect(formatErrorCause({})).toBe('Elasticsearch returned an error');
   });
@@ -138,4 +160,35 @@ describe('EsqlResponseError', () => {
 
     expect(err.status).toBe(400);
   });
+
+  it('formats message from multiple root_cause entries when top-level type and reason are absent', () => {
+    const err = new EsqlResponseError({
+      root_cause: [
+        { type: 'index_not_found_exception', reason: 'no such index [cluster-a:metrics-*]' },
+        { type: 'index_not_found_exception', reason: 'no such index [cluster-b:metrics-*]' },
+      ],
+    });
+
+    expect(err.message).toBe(
+      'index_not_found_exception: no such index [cluster-a:metrics-*]\nindex_not_found_exception: no such index [cluster-b:metrics-*]'
+    );
+  });
+});
+
+describe('isEsqlResponseError', () => {
+  it('preserves prototype chain so instanceof works after downlevel emit', () => {
+    const err = new EsqlResponseError({ type: 'x', reason: 'y' });
+
+    expect(Object.getPrototypeOf(err)).toBe(EsqlResponseError.prototype);
+    expect(isEsqlResponseError(err)).toBe(true);
+  });
+
+  it('returns true for EsqlResponseError instances', () => {
+    expect(isEsqlResponseError(new EsqlResponseError({ type: 'x', reason: 'y' }))).toBe(true);
+  });
+
+  it('returns false for other errors', () => {
+    expect(isEsqlResponseError(new Error('network'))).toBe(false);
+    expect(isEsqlResponseError(undefined)).toBe(false);
+  });
 });

…nents/chart/utils/esql_response_error.ts …src/common/errors/esql_response_error.tssrc/platform/packages/shared/kbn-unified-chart-section-viewer/src/components/chart/utils/esql_response_error.ts renamed to src/platform/packages/shared/kbn-unified-chart-section-viewer/src/common/errors/esql_response_error.ts src/platform/packages/shared/kbn-unified-chart-section-viewer/src/components/chart/utils/esql_response_error.ts renamed to src/platform/packages/shared/kbn-unified-chart-section-viewer/src/common/errors/esql_response_error.ts

@@ -7,24 +7,46 @@
  * License v3.0 only", or the "Server Side Public License, v 1".
  */
 
-// TODO https://github.com/elastic/kibana/issues/260667
 import type { estypes } from '@elastic/elasticsearch';
 
 export type EsqlResponseErrorCause = Partial<estypes.ErrorCause>;
 
-export const formatErrorCause = (errorCause: EsqlResponseErrorCause): string => {
-  const head = [errorCause.type, errorCause.reason]
+const formatSingleCause = (cause: EsqlResponseErrorCause): string | undefined => {
+  const formatted = [cause.type, cause.reason]
     .filter((value): value is string => Boolean(value?.trim()))
     .join(': ');
+  return formatted || undefined;
+};
+
+const formatRootCauses = (rootCauses: EsqlResponseErrorCause[] | undefined): string | undefined => {
+  if (!rootCauses?.length) {
+    return undefined;
+  }
+
+  const formatted = rootCauses
+    .map((cause) => formatSingleCause(cause))
+    .filter((value): value is string => Boolean(value));
+
+  return formatted.length > 0 ? formatted.join('\n') : undefined;
+};
+
+/**
+ * Builds a human-readable message from an Elasticsearch error cause, including
+ * all `root_cause` entries (e.g. CCS / multi-cluster failures).
+ */
+export const formatErrorCause = (errorCause: EsqlResponseErrorCause): string => {
+  const head = formatSingleCause(errorCause);
   if (head) {
     return head;
   }
 
-  const rootCause = errorCause.root_cause?.[0];
-  const fromRootCause = [rootCause?.type, rootCause?.reason]
-    .filter((value): value is string => Boolean(value?.trim()))
-    .join(': ');
-  return fromRootCause || 'Elasticsearch returned an error';
+  const fromRootCauses = formatRootCauses(errorCause.root_cause);
+  if (fromRootCauses) {
+    return fromRootCauses;
+  }
+
+  const fromCausedBy = errorCause.caused_by ? formatSingleCause(errorCause.caused_by) : undefined;
+  return fromCausedBy || 'Elasticsearch returned an error';
 };
 
 export interface EsqlEmbeddedError {
@@ -61,5 +83,12 @@ export class EsqlResponseError extends Error {
     this.reason = errorCause.reason ?? undefined;
     this.rootCause = errorCause.root_cause;
     this.status = options?.status;
+
+    // Set the prototype explicitly, see:
+    // https://github.com/Microsoft/TypeScript/wiki/Breaking-Changes#extending-built-ins-like-error-array-and-map-may-no-longer-work
+    Object.setPrototypeOf(this, EsqlResponseError.prototype);
   }
 }
+
+export const isEsqlResponseError = (error: unknown): error is EsqlResponseError =>
+  error instanceof EsqlResponseError;

src/platform/packages/shared/kbn-unified-chart-section-viewer/src/common/errors/normalize_chart_section_search_error.test.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import { EsqlResponseError } from './esql_response_error';
+import { normalizeChartSectionSearchError } from './normalize_chart_section_search_error';
+
+describe('normalizeChartSectionSearchError', () => {
+  it('returns the same Error instance', () => {
+    const error = new Error('network');
+    expect(normalizeChartSectionSearchError(error)).toBe(error);
+  });
+
+  it('returns EsqlResponseError instances unchanged', () => {
+    const error = new EsqlResponseError({ type: 'x', reason: 'y' });
+    expect(normalizeChartSectionSearchError(error)).toBe(error);
+  });
+
+  it('wraps non-empty strings in Error', () => {
+    const error = normalizeChartSectionSearchError('fetch failed');
+    expect(error).toBeInstanceOf(Error);
+    expect(error.message).toBe('fetch failed');
+  });
+
+  it('wraps other values with String()', () => {
+    expect(normalizeChartSectionSearchError(42).message).toBe('42');
+    expect(normalizeChartSectionSearchError(null).message).toBe('null');
+  });
+});

src/platform/packages/shared/kbn-unified-chart-section-viewer/src/common/errors/normalize_chart_section_search_error.ts

@@ -0,0 +1,20 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+/**
+ * Normalizes fetch-layer failures from chart section ES|QL queries into an `Error`
+ * suitable for Discover's `ErrorCallout` and related display helpers.
+ */
+export const normalizeChartSectionSearchError = (error: unknown): Error => {
+  if (error instanceof Error) {
+    return error;
+  }
+
+  return new Error(String(error));
+};

src/platform/packages/shared/kbn-unified-chart-section-viewer/src/components/chart/hooks/use_report_chart_section_error.test.tsx

@@ -12,12 +12,12 @@ import type { Logger } from '@kbn/logging';
 import { loggerMock } from '@kbn/logging-mocks';
 import { renderHook } from '@testing-library/react';
 import React from 'react';
+import { EsqlResponseError } from '../../../common/errors/esql_response_error';
 import {
   ExternalServicesProvider,
   type ExternalServices,
 } from '../../../context/external_services';
 import { ERROR_TYPE } from '../../../utils/error_labels';
-import { EsqlResponseError } from '../utils/esql_response_error';
 import {
   type ReportChartSectionErrorArgs,
   useReportChartSectionError,

src/platform/packages/shared/kbn-unified-chart-section-viewer/src/components/chart/hooks/use_report_chart_section_error.ts

@@ -13,7 +13,7 @@ import { useCallback } from 'react';
 import { useExternalServices } from '../../../context/external_services';
 import { ERROR_TYPE } from '../../../utils/error_labels';
 import { toLoggable } from '../../../utils/logger_utils';
-import { EsqlResponseError } from '../utils/esql_response_error';
+import { EsqlResponseError } from '../../../common/errors/esql_response_error';
 import { isSuppressedFetchError } from '../utils/is_suppressed_fetch_error';
 
 /** APM label identifying which chart-section call site produced an error. */

src/platform/packages/shared/kbn-unified-chart-section-viewer/src/components/chart_section_search_error/chart_section_search_error.test.tsx

@@ -0,0 +1,79 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import { EuiProvider } from '@elastic/eui';
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+import { EsqlResponseError } from '../../common/errors/esql_response_error';
+import { ExternalServicesProvider, type ExternalServices } from '../../context/external_services';
+import { ChartSectionSearchError } from './chart_section_search_error';
+
+const renderChartSectionSearchError = (
+  ui: React.ReactElement,
+  externalServices?: ExternalServices
+) =>
+  render(
+    <EuiProvider highContrastMode={false}>
+      <ExternalServicesProvider externalServices={externalServices}>{ui}</ExternalServicesProvider>
+    </EuiProvider>
+  );
+
+describe('ChartSectionSearchError', () => {
+  it('renders Discover ErrorCallout with title and error message', () => {
+    const error = new Error('Network error');
+
+    renderChartSectionSearchError(
+      <ChartSectionSearchError error={error} title="Unable to retrieve search results" />
+    );
+
+    expect(screen.getByTestId('discoverErrorCalloutTitle')).toHaveTextContent(
+      'Unable to retrieve search results'
+    );
+    expect(screen.getByTestId('discoverErrorCalloutMessage')).toHaveTextContent('Network error');
+  });
+
+  it('normalizes non-Error fetch failures before display', () => {
+    renderChartSectionSearchError(
+      <ChartSectionSearchError error="fetch failed" title="Unable to retrieve search results" />
+    );
+
+    expect(screen.getByTestId('discoverErrorCalloutMessage')).toHaveTextContent('fetch failed');
+  });
+
+  it('displays EsqlResponseError messages from embedded Elasticsearch errors', () => {
+    const error = new EsqlResponseError({
+      type: 'illegal_argument_exception',
+      reason: 'invalid field',
+    });
+
+    renderChartSectionSearchError(
+      <ChartSectionSearchError error={error} title="Unable to retrieve search results" />
+    );
+
+    expect(screen.getByTestId('discoverErrorCalloutMessage')).toHaveTextContent(
+      'illegal_argument_exception: invalid field'
+    );
+  });
+
+  it('renders ES|QL reference link when externalServices provides docLinks', () => {
+    renderChartSectionSearchError(
+      <ChartSectionSearchError error={new Error('x')} title="Unable to retrieve search results" />,
+      {
+        docLinks: {
+          links: { query: { queryESQL: 'https://www.elastic.co/docs/reference/esql' } },
+        },
+      } as ExternalServices
+    );
+
+    expect(screen.getByTestId('discoverErrorCalloutESQLReferenceButton')).toHaveAttribute(
+      'href',
+      'https://www.elastic.co/docs/reference/esql'
+    );
+  });
+});

src/platform/packages/shared/kbn-unified-chart-section-viewer/src/components/chart_section_search_error/chart_section_search_error.tsx

@@ -0,0 +1,36 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import React from 'react';
+import { ErrorCallout } from '@kbn/discover-utils';
+import { normalizeChartSectionSearchError } from '../../common/errors/normalize_chart_section_search_error';
+import { useExternalServices } from '../../context/external_services';
+
+export interface ChartSectionSearchErrorProps {
+  error: unknown;
+  title: string;
+}
+
+/**
+ * Chart-section fetch failures (METRICS_INFO, Traces, etc.) using Discover's ErrorCallout.
+ * Host injects notifications and doc links via `ExternalServicesProvider`.
+ */
+export const ChartSectionSearchError = ({ error, title }: ChartSectionSearchErrorProps) => {
+  const services = useExternalServices();
+
+  return (
+    <ErrorCallout
+      title={title}
+      error={normalizeChartSectionSearchError(error)}
+      isEsqlMode
+      showErrorDialog={services?.notifications?.showErrorDialog}
+      esqlReferenceHref={services?.docLinks?.links.query.queryESQL}
+    />
+  );
+};

src/platform/packages/shared/kbn-unified-chart-section-viewer/src/components/observability/metrics/hooks/use_fetch_metrics_data.test.ts

@@ -59,6 +59,7 @@ import type { ChartSectionProps } from '@kbn/unified-histogram/types';
 import type { Dimension, ParsedMetricsWithTelemetry } from '../../../../types';
 import { useFetchMetricsData } from './use_fetch_metrics_data';
 import { executeEsqlQuery } from '../utils/execute_esql_query';
+import { EsqlResponseError } from '../../../../common/errors/esql_response_error';
 import { parseMetricsWithTelemetry } from '../utils/parse_metrics_response_with_telemetry';
 import { getFetchParamsMock } from '@kbn/unified-histogram/__mocks__/fetch_params';
 
@@ -468,11 +469,40 @@ describe('useFetchMetricsData', () => {
         expect(result.current.error).toBeTruthy();
       });
 
+      expect(result.current.error).toBe(fetchError);
       expect(result.current.metricItems).toEqual([]);
       expect(result.current.allDimensions).toEqual([]);
       expect(result.current.activeDimensions).toEqual([]);
     });
 
+    it('returns EsqlResponseError when ES|QL responds with HTTP 200 and embedded error', async () => {
+      const embeddedError = new EsqlResponseError(
+        {
+          type: 'remote_transport_exception',
+          reason: 'ccs query failed',
+          root_cause: [{ type: 'index_not_found_exception', reason: 'no such index [metrics-*]' }],
+        },
+        { status: 400 }
+      );
+      mockExecuteEsqlQuery.mockRejectedValue(embeddedError);
+
+      const params = createDefaultParams();
+      const { result } = renderHook(() => useFetchMetricsData(params));
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+        expect(result.current.error).toBe(embeddedError);
+      });
+
+      expect(result.current.error).toBeInstanceOf(EsqlResponseError);
+      expect(result.current.error).toMatchObject({
+        message: 'remote_transport_exception: ccs query failed',
+        status: 400,
+        rootCause: [{ type: 'index_not_found_exception', reason: 'no such index [metrics-*]' }],
+      });
+      expect(result.current.metricItems).toEqual([]);
+    });
+
     it('returns empty arrays and null error in initial state', () => {
       // Delay fetch indefinitely so we can inspect the initial state
       mockExecuteEsqlQuery.mockReturnValue(new Promise(() => {}));