From 634e0b43029e85e97b1ef42da66e5a781a08d091 Mon Sep 17 00:00:00 2001
From: Steven H <steven@gitbook.io>
Date: Wed, 23 Apr 2025 12:47:28 +0100
Subject: [PATCH] Improve error messages around undefined site sections.
 (#3179)

---
 .changeset/soft-planes-talk.md         |  5 +++
 packages/gitbook-v2/src/lib/context.ts | 51 ++++++++++++++++++++------
 2 files changed, 44 insertions(+), 12 deletions(-)
 create mode 100644 .changeset/soft-planes-talk.md

diff --git a/.changeset/soft-planes-talk.md b/.changeset/soft-planes-talk.md
new file mode 100644
index 000000000..d633d90dc
--- /dev/null
+++ b/.changeset/soft-planes-talk.md
@@ -0,0 +1,5 @@
+---
+"gitbook-v2": patch
+---
+
+Improve error messages around undefined site sections.
diff --git a/packages/gitbook-v2/src/lib/context.ts b/packages/gitbook-v2/src/lib/context.ts
index d25dd1946..7ef0f463b 100644
--- a/packages/gitbook-v2/src/lib/context.ts
+++ b/packages/gitbook-v2/src/lib/context.ts
@@ -19,6 +19,7 @@ import {
     getDataOrNull,
     throwIfDataError,
 } from '@v2/lib/data';
+import assertNever from 'assert-never';
 import { notFound } from 'next/navigation';
 import { assert } from 'ts-essentials';
 import { GITBOOK_URL } from './env';
@@ -242,19 +243,45 @@ export async function fetchSiteContextByIds(
         ? parseSiteSectionsAndGroups(siteStructure, ids.siteSection)
         : null;
 
-    const siteSpace = (
-        siteStructure.type === 'siteSpaces' && siteStructure.structure
-            ? siteStructure.structure
-            : sections?.current.siteSpaces
-    )?.find((siteSpace) => siteSpace.id === ids.siteSpace);
-    if (!siteSpace) {
-        throw new Error('Site space not found');
-    }
+    // Parse the current siteSpace and siteSpaces based on the site structure type.
+    const { siteSpaces, siteSpace }: { siteSpaces: SiteSpace[]; siteSpace: SiteSpace } = (() => {
+        if (siteStructure.type === 'siteSpaces') {
+            const siteSpaces = siteStructure.structure;
+            const siteSpace = siteSpaces.find((siteSpace) => siteSpace.id === ids.siteSpace);
 
-    const siteSpaces =
-        siteStructure.type === 'siteSpaces'
-            ? siteStructure.structure
-            : (sections?.current.siteSpaces ?? []);
+            if (!siteSpace) {
+                throw new Error(
+                    `Site space "${ids.siteSpace}" not found in structure type="siteSpaces"`
+                );
+            }
+
+            return { siteSpaces, siteSpace };
+        }
+
+        if (siteStructure.type === 'sections') {
+            assert(
+                sections,
+                `cannot find site space "${ids.siteSpace}" because parsed sections are missing siteStructure.type="sections" siteSection="${ids.siteSection}"`
+            );
+
+            const currentSection = sections.current;
+            const siteSpaces = currentSection.siteSpaces;
+            const siteSpace = currentSection.siteSpaces.find(
+                (siteSpace) => siteSpace.id === ids.siteSpace
+            );
+
+            if (!siteSpace) {
+                throw new Error(
+                    `Site space "${ids.siteSpace}" not found in structure type="sections" currentSection="${currentSection.id}"`
+                );
+            }
+
+            return { siteSpaces, siteSpace };
+        }
+
+        // @ts-expect-error
+        assertNever(siteStructure, `cannot handle site structure of type ${siteStructure.type}`);
+    })();
 
     const customization = (() => {
         if (ids.siteSpace) {