From 63e4a579e88bfb2039b3a9bc22eb8292dfb7cd40 Mon Sep 17 00:00:00 2001
From: Lukas Harbarth <lukas.harbarth@sap.com>
Date: Mon, 9 Mar 2026 08:39:20 +0100
Subject: [PATCH] docs(AnalyticalTable): add error log for nested headers

---
 packages/main/src/components/AnalyticalTable/index.tsx    | 8 ++++++++
 .../main/src/components/AnalyticalTable/types/index.ts    | 3 +++
 2 files changed, 11 insertions(+)

diff --git a/packages/main/src/components/AnalyticalTable/index.tsx b/packages/main/src/components/AnalyticalTable/index.tsx
index 8e9e86b4073..4250d95e720 100644
--- a/packages/main/src/components/AnalyticalTable/index.tsx
+++ b/packages/main/src/components/AnalyticalTable/index.tsx
@@ -346,6 +346,14 @@ const AnalyticalTable = forwardRef<AnalyticalTableDomRef, AnalyticalTablePropTyp
     setGlobalFilter,
   } = tableInstanceRef.current;
 
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'development' && headerGroups.length > 1) {
+      console.error(
+        '[AnalyticalTable] Nested column headers are not supported. Please flatten your column definitions.',
+      );
+    }
+  }, [headerGroups.length]);
+
   const tableState: AnalyticalTableState = tableInstanceRef.current.state;
   const { popInColumns, triggerScroll } = tableState;
   const isGrouped = !!tableState.groupBy.length;
diff --git a/packages/main/src/components/AnalyticalTable/types/index.ts b/packages/main/src/components/AnalyticalTable/types/index.ts
index e3a08944b58..2555aa7b771 100644
--- a/packages/main/src/components/AnalyticalTable/types/index.ts
+++ b/packages/main/src/components/AnalyticalTable/types/index.ts
@@ -166,6 +166,9 @@ export interface TableInstance {
   groupedFlatRows?: RowType[];
   groupedRows?: RowType[];
   groupedRowsById?: Record<string, RowType>;
+  /**
+   * Nested column headers are not supported. This array must only contain a single header group.
+   */
   headerGroups: Record<string, any>[];
   headers: ColumnType[];
   initialRows: RowType[];