From 53338caa85c4ea726af11a311ba18e7110826312 Mon Sep 17 00:00:00 2001
From: Rob Simmons <robsimmons@gmail.com>
Date: Thu, 6 Aug 2026 11:52:42 -0400
Subject: [PATCH 1/7] refactor: add and use error boundaries

apply pattern in a few more cases


more agent commentary
---
 AGENTS.md                                     | 21 +++++++-
 doc/DEVELOPMENT.md                            |  2 +-
 src/app/[userName]/NewProjectForm.tsx         | 11 ++--
 src/app/[userName]/[projectName]/page.tsx     | 10 +---
 src/app/[userName]/actions.ts                 | 31 ++++++-----
 src/app/admin/actions.ts                      |  3 +-
 src/app/admin/components/OAuthConfig.tsx      |  4 +-
 .../components/{Error.tsx => ErrorBox.tsx}    |  0
 src/app/error.tsx                             | 52 +++++++++++++++++++
 src/app/global-error.tsx                      | 21 ++++++++
 src/app/page.tsx                              | 14 ++---
 src/app/setup/page.tsx                        | 38 ++++++++++----
 12 files changed, 157 insertions(+), 50 deletions(-)
 rename src/app/components/{Error.tsx => ErrorBox.tsx} (100%)
 create mode 100644 src/app/error.tsx
 create mode 100644 src/app/global-error.tsx

diff --git a/AGENTS.md b/AGENTS.md
index 4bc66445..25b020a8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,10 +22,27 @@
   For example, prefer one state of type `'loading' | { error: E } | { result: T }`
   to three states `[loading, setLoading] = useState(); [error, setError] = useState(); [result, setResult] = useState()`.
 - For UI actions that hit the server,
-prefer `useServerAction` (`@/lib/util`) or (if `useServerAction` doesn't work) `useActionState`
+prefer `useServerAction` (`@/lib/client/util`) or (if `useServerAction` doesn't work) `useActionState`
 over manually storing response/error state with `useState`.
 - To call Server Functions on mount (e.g. to fetch data), use SWR.
-  
+
+# Error handling
+
+- Next.js interrupts are preferred when there is something appropriate available (e.g. authentication errors, forbidden())
+- ActionResponse { error } states are only for failures the user is expected to be able to encounter during usual operation,
+  and is expected to be able to act on (e.g. "A project with that name already exists").
+- Everything else (bugs, unreachable services, misconfigured hosts) should throw to an error boundary.
+- Errors thrown within the app should not be converted to ActionResponse errors, and vice versa.
+
+Some details/consequences:
+
+- Only render-phase throws hit error boundaries;
+  avoid throwing in callbacks, event handlers, and timeouts that will be silently ignored.
+- SWR puts a fetcher's throw in `error`;
+  errors from SWR should generally be re-raised inside of the React render function.
+  Sometimes SWR errors should be shown to the user instead,
+  but they should not be suppressed or ignored.
+
 # Agent instructions
 
 - Less code is better. After writing any new piece of code,
diff --git a/doc/DEVELOPMENT.md b/doc/DEVELOPMENT.md
index 5a7a6ce9..d88509d6 100644
--- a/doc/DEVELOPMENT.md
+++ b/doc/DEVELOPMENT.md
@@ -8,7 +8,7 @@ It describes how to locally run and test the workbench software.
 - Docker installed and running,
   with at least 16GB memory allocated
   (in Docker Desktop, go to Settings -> Resources -> Memory).
-- Node v24 or later is needed for `make` to work
+- Node v24 or later is needed for `make container` to work
 
 ## Running the workbench server
 
diff --git a/src/app/[userName]/NewProjectForm.tsx b/src/app/[userName]/NewProjectForm.tsx
index 50f6fbd8..bb660326 100644
--- a/src/app/[userName]/NewProjectForm.tsx
+++ b/src/app/[userName]/NewProjectForm.tsx
@@ -16,11 +16,8 @@ export function NewProjectForm() {
     data: templates,
     error: templatesError,
     isLoading: templatesPending,
-  } = useSWR<TemplateInfo[], string>('listTemplates', async () => {
-    const result = await listTemplates()
-    if ('error' in result) throw new Error(result.error)
-    return result.ok
-  })
+  } = useSWR<TemplateInfo[], unknown>('listTemplates', listTemplates)
+  if (templatesError) throw templatesError
 
   const [chosenTemplate, setChosenTemplate] = useState<string>('blank')
 
@@ -46,8 +43,6 @@ export function NewProjectForm() {
     )
   }
 
-  const error = templatesError ?? createError
-
   return (
     <form action={createAction} className='new-project' style={{ marginTop: 16 }}>
       <input
@@ -76,7 +71,7 @@ export function NewProjectForm() {
           </button>
         ))}
       </div>
-      {error && <div style={{ color: '#dc2626', fontSize: 13, marginBottom: 8 }}>{error}</div>}
+      {createError && <div style={{ color: '#dc2626', fontSize: 13, marginBottom: 8 }}>{createError}</div>}
       <div>
         <button type='submit' disabled={createPending}>
           Create
diff --git a/src/app/[userName]/[projectName]/page.tsx b/src/app/[userName]/[projectName]/page.tsx
index c606d378..36aa712a 100644
--- a/src/app/[userName]/[projectName]/page.tsx
+++ b/src/app/[userName]/[projectName]/page.tsx
@@ -1,7 +1,6 @@
 import { notFound } from 'next/navigation'
 import z from 'zod'
 
-import Error from '@/app/components/Error'
 import { requireAuth } from '@/lib/server/auth'
 import { getDb } from '@/lib/server/db'
 import { getEditorSessionManager } from '@/lib/server/editorSessions'
@@ -36,13 +35,8 @@ export default async function EditorSession({ params: params_ }: { params: Promi
   if (!project || !canAccessProject(viewer, project)) notFound()
 
   const manager = getEditorSessionManager()
-  let iframeSrc: string
-  try {
-    iframeSrc = await manager.ensureSession(viewer, owner, project)
-  } catch (err) {
-    console.error('Failed to start editor session:', (err as Error).message)
-    return <Error>Failed to start editor session: {String(err)}</Error>
-  }
+  // may throw to error boundary (e.g. if the project folder isn't accessible)
+  const iframeSrc = await manager.ensureSession(viewer, owner, project)
 
   // TODO: VSC should be sandboxed but can't be opaque-origin: need a subdomain.
   return <iframe id='editor-frame' src={iframeSrc} className='editor-session-iframe' />
diff --git a/src/app/[userName]/actions.ts b/src/app/[userName]/actions.ts
index 1338bb36..c73a6277 100644
--- a/src/app/[userName]/actions.ts
+++ b/src/app/[userName]/actions.ts
@@ -22,10 +22,13 @@ const zTemplateMetadata = z.object({
 
 type TemplateMetadata = z.infer<typeof zTemplateMetadata>
 
-async function readTemplateMetadata(templateDir: string): Promise<TemplateMetadata | null> {
+/**
+ * Read `metadata.json` from `templateDir`,
+ * raising an exception if the file is missing or does not work.
+ */
+async function readTemplateMetadata(templateDir: string): Promise<TemplateMetadata> {
   const metaPath = path.join(templateDir, 'metadata.json')
-  const raw = await fs.readFile(metaPath, 'utf-8').catch(() => null)
-  if (raw === null) return null
+  const raw = await fs.readFile(metaPath, 'utf-8')
   return zTemplateMetadata.parse(JSON.parse(raw))
 }
 
@@ -43,18 +46,23 @@ export interface TemplateInfo {
 
 // --- Queries ---
 
-export async function listTemplates(): Promise<ActionResponse<TemplateInfo[]>> {
+export async function listTemplates(): Promise<TemplateInfo[]> {
   await requireAuth()
 
   const templatesDir = getTemplatesDir()
 
   const result: TemplateInfo[] = [{ id: 'blank', name: 'Blank', description: 'Empty workspace' }]
-  const entries = await fs.readdir(templatesDir, { withFileTypes: true }).catch(() => [])
+  const entries = await fs.readdir(templatesDir, { withFileTypes: true })
 
   for (const entry of entries) {
     if (!entry.isDirectory()) continue
-    const meta = await readTemplateMetadata(path.join(entry.parentPath, entry.name))
-    if (!meta) continue
+    let meta: TemplateMetadata
+    try {
+      meta = await readTemplateMetadata(path.join(entry.parentPath, entry.name))
+    } catch (err) {
+      console.error(`Skipping ${entry.name} due to metadata error`, err)
+      continue
+    }
     result.push({
       id: entry.name,
       name: meta.name,
@@ -62,7 +70,7 @@ export async function listTemplates(): Promise<ActionResponse<TemplateInfo[]>> {
     })
   }
 
-  return { ok: result }
+  return result
 }
 
 // --- Mutations ---
@@ -84,13 +92,10 @@ export const createProject = serverAction(
     if (template !== 'blank') {
       const templateDir = path.join(getTemplatesDir(), template)
       const meta = await readTemplateMetadata(templateDir)
-      if (!meta) return { error: `Template "${template}" not found` }
       if (meta.packageSet) {
         const packagesFile = path.join(getPackageSetsDir(), meta.packageSet, 'packages.txt')
         if (!(await existsAsync(packagesFile))) {
-          return {
-            error: `Package set "${meta.packageSet}" not found. Run seed-volume.sh first.`,
-          }
+          throw new Error(`Package set "${meta.packageSet}" not found. Run seed-volume.sh first.`)
         }
       }
     }
@@ -114,7 +119,7 @@ export const createProject = serverAction(
       await fs.rm(path.join(workspace, 'metadata.json'), { force: true })
 
       const meta = await readTemplateMetadata(templateDir)
-      packageSet = meta?.packageSet
+      packageSet = meta.packageSet
     }
 
     // Store project in DB
diff --git a/src/app/admin/actions.ts b/src/app/admin/actions.ts
index cde458f9..c6b74fac 100644
--- a/src/app/admin/actions.ts
+++ b/src/app/admin/actions.ts
@@ -196,7 +196,8 @@ export async function fetchDiskUsage(): Promise<ActionResponse<{ workspaces: str
     const size = out.split('\t')[0] ?? '?'
     return { ok: { workspaces: size } }
   } catch (e: unknown) {
-    return { error: `Failed to compute disk usage: ${e instanceof Error ? e.message : String(e)}` }
+    console.error(`Failed to compute directory usage`, e)
+    return { error: `Could not compute size (the directory may be too large)` }
   }
 }
 
diff --git a/src/app/admin/components/OAuthConfig.tsx b/src/app/admin/components/OAuthConfig.tsx
index 64330f9e..08eb4d08 100644
--- a/src/app/admin/components/OAuthConfig.tsx
+++ b/src/app/admin/components/OAuthConfig.tsx
@@ -8,7 +8,9 @@ import { useServerAction } from '@/lib/client/util'
 import { formString } from '@/lib/util'
 
 export function OAuthConfig() {
-  const { data, mutate } = useSWR('adminOAuthConfig', () => fetchOAuthConfig())
+  const { data, mutate, error: oauthConfigError } = useSWR('adminOAuthConfig', () => fetchOAuthConfig())
+  if (oauthConfigError) throw oauthConfigError
+
   const [editing, setEditing] = useState(false)
 
   const [error, action, pending] = useServerAction(
diff --git a/src/app/components/Error.tsx b/src/app/components/ErrorBox.tsx
similarity index 100%
rename from src/app/components/Error.tsx
rename to src/app/components/ErrorBox.tsx
diff --git a/src/app/error.tsx b/src/app/error.tsx
new file mode 100644
index 00000000..7686d2e2
--- /dev/null
+++ b/src/app/error.tsx
@@ -0,0 +1,52 @@
+'use client'
+
+import { useEffect } from 'react'
+import { useSWRConfig } from 'swr'
+
+import ErrorBox from './components/ErrorBox'
+
+interface ErrorBoundaryProps {
+  error: Error & { digest?: string }
+  retry: () => void
+}
+
+/**
+ * App-level error boundary
+ * https://nextjs.org/docs/app/api-reference/file-conventions/error
+ */
+export default function ErrorBoundary({ error, retry }: ErrorBoundaryProps) {
+  const { mutate } = useSWRConfig()
+  useEffect(() => {
+    console.error('Unhandled error:', error, error.digest)
+  }, [error])
+
+  return (
+    <div>
+      <h1>Something went wrong!</h1>
+      <ErrorBox>
+        {error.digest && (
+          <p>
+            Something went wrong on the server. Try again, or contact your administrator with the error code{' '}
+            {error.digest} if the problem persists.
+          </p>
+        )}
+        {!error.digest && <p>An unexpected error occurred: {error.message}</p>}
+      </ErrorBox>
+      <button
+        onClick={async () => {
+          try {
+            // Invalidate all SWR state, but don't re-fetch automatically
+            await mutate(() => true, undefined, { revalidate: false })
+          } catch (e) {
+            console.error('Failed to clear SWR cache', e)
+          }
+
+          //Attempt to recover by re-rendering
+          retry()
+        }}
+      >
+        Try again
+      </button>
+    </div>
+  )
+}
diff --git a/src/app/global-error.tsx b/src/app/global-error.tsx
new file mode 100644
index 00000000..67835dad
--- /dev/null
+++ b/src/app/global-error.tsx
@@ -0,0 +1,21 @@
+'use client'
+
+interface ErrorBoundaryProps {
+  error: Error & { digest?: string }
+}
+
+/**
+ * Error boundary for the app root
+ * https://nextjs.org/docs/app/api-reference/file-conventions/error#global-error
+ */
+export default function GlobalError({ error }: ErrorBoundaryProps) {
+  return (
+    <html>
+      <body>
+        <h1>Something went wrong!</h1>
+        <p>Contact your administrator if you continue to see this message.</p>
+        {error.digest && <p>(Error code {error.digest})</p>}
+      </body>
+    </html>
+  )
+}
diff --git a/src/app/page.tsx b/src/app/page.tsx
index 71c1ed11..f58485af 100644
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@@ -7,11 +7,12 @@ import { useSearchParams } from 'next/navigation'
 import authClient from '@/lib/client/auth'
 import { type Config, useConfigCtx } from '@/lib/contexts'
 
-import Error from './components/Error'
+import ErrorBox from './components/ErrorBox'
 
-type ErrorParam = 'unable_to_create_user' | string
-
-function errorParamToMsg(e: ErrorParam, cfg: Config): string {
+/**
+ * Interprets an (untrusted) `error` search parameter as OAuth callback information
+ */
+function errorParamToMsg(e: string, cfg: Config): string {
   if (e === 'unable_to_create_user') {
     let msg = 'Could not sign up.'
     if (cfg.registrationMode === 'restricted') {
@@ -21,7 +22,8 @@ function errorParamToMsg(e: ErrorParam, cfg: Config): string {
   } else if (e === 'invalid_code') {
     return 'Invalid GitHub OAuth configuration. Ask your administrator to fix it.'
   } else {
-    return e
+    // An unrecognized search parameter should not be shown directly to the user (phishing risk)
+    return 'Unexpected sign-in failure. Please try again; contact your administrator if this error continues.'
   }
 }
 
@@ -32,7 +34,7 @@ export default function Root() {
 
   return (
     <>
-      {error && <Error>Error: {errorParamToMsg(error, cfg)}</Error>}
+      {error && <ErrorBox>Error logging in: {errorParamToMsg(error, cfg)}</ErrorBox>}
       <h1>Lean Workbench</h1>
       <p>Multi-user sandboxed VS Code server.</p>
       {session.data && (
diff --git a/src/app/setup/page.tsx b/src/app/setup/page.tsx
index bdc97ba8..b922020c 100644
--- a/src/app/setup/page.tsx
+++ b/src/app/setup/page.tsx
@@ -8,7 +8,7 @@ import { z } from 'zod'
 
 import { useServerAction } from '@/lib/client/util'
 import { useConfigCtx } from '@/lib/contexts'
-import { LEAN_VERSION_RE, zSeedEvent } from '@/lib/util'
+import { LEAN_VERSION_RE, SeedEvent, zSeedEvent } from '@/lib/util'
 
 import { fetchSetupStatus, saveSetupConfig, startSeed } from './actions'
 
@@ -37,7 +37,9 @@ export default function Setup() {
   const [progress, setProgress] = useState({ pct: 0, label: '' })
   const [logs, setLogs] = useState<string[]>([])
   const [leanVersion, setLeanVersion] = useState<string | undefined>()
-  const { data: leanVersions } = useSWR('leanVersions', fetchLeanVersions)
+  const { data: leanVersions, error: leanVersionsError } = useSWR('leanVersions', fetchLeanVersions)
+  if (leanVersionsError) throw leanVersionsError
+
   const logRef = useRef<HTMLDivElement>(null)
 
   const [configError, saveConfigAction, savingConfig] = useServerAction(
@@ -66,7 +68,17 @@ export default function Setup() {
     if (phase !== 'seeding') return
     const source = new EventSource('/api/setup-events')
     source.onmessage = event => {
-      const data = zSeedEvent.parse(JSON.parse(event.data as string /* EventSources ensure this in practice */))
+      let data: SeedEvent
+      try {
+        data = zSeedEvent.parse(JSON.parse(event.data as string /* EventSources ensure this in practice */))
+      } catch (err) {
+        source.close()
+        console.error('Error parsing a response from EventSource setup-events: ', err)
+        setSeedError('Unexpected response from server')
+        setPhase('error')
+        return
+      }
+
       switch (data.type) {
         case 'progress': {
           const pct = Math.round((data.step / data.total) * 100)
@@ -92,13 +104,19 @@ export default function Setup() {
       }
     }
     source.onerror = async () => {
-      source.close()
-      const status = await fetchSetupStatus()
-      if (status.seeded) {
-        setProgress({ pct: 100, label: '' })
-        setPhase('done')
-      } else if (!status.seeding) {
-        setSeedError('Connection lost')
+      try {
+        source.close()
+        const status = await fetchSetupStatus()
+        if (status.seeded) {
+          setProgress({ pct: 100, label: '' })
+          setPhase('done')
+        } else if (!status.seeding) {
+          setSeedError('Connection lost')
+          setPhase('error')
+        }
+      } catch (e) {
+        console.error('fetchSetupStatus() failed', e)
+        setSeedError('Unexpected error getting setup status')
         setPhase('error')
       }
     }

From 0ad14d9fcb2a9ed98cd93d924becc98c9fdb9b77 Mon Sep 17 00:00:00 2001
From: Rob Simmons <robsimmons@gmail.com>
Date: Fri, 7 Aug 2026 14:49:07 -0400
Subject: [PATCH 2/7] additional abstractions and error handling

---
 AGENTS.md                                | 12 ++++++---
 src/app/AvatarMenu.tsx                   | 33 +++++++++++++++++-------
 src/app/[userName]/NewProjectForm.tsx    | 12 +++------
 src/app/[userName]/actions.ts            |  2 +-
 src/app/admin/components/OAuthConfig.tsx |  6 ++---
 src/app/forbidden.tsx                    | 12 +++++++++
 src/app/page.tsx                         | 12 +++++----
 src/app/setup/page.tsx                   | 12 ++++-----
 src/app/unauthorized.tsx                 | 12 +++++++++
 src/lib/client/auth.ts                   |  2 ++
 src/lib/client/util.ts                   | 30 +++++++++++++++++++--
 src/lib/util.ts                          |  3 +++
 12 files changed, 107 insertions(+), 41 deletions(-)
 create mode 100644 src/app/forbidden.tsx
 create mode 100644 src/app/unauthorized.tsx

diff --git a/AGENTS.md b/AGENTS.md
index 25b020a8..57bede2e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -37,11 +37,17 @@ over manually storing response/error state with `useState`.
 Some details/consequences:
 
 - Only render-phase throws hit error boundaries;
-  avoid throwing in callbacks, event handlers, and timeouts that will be silently ignored.
+  exceptions originating from callbacks, event handlers, and timeouts must not be silently ignored.
+  Next.js gives advice for handling these cases (https://nextjs.org/docs/app/getting-started/error-handling),
+  generally we want to show the error to the user in the component
+  or else re-raise to throw to an error boundary (`throwToBoundary` is useful here).
+  (depending on whether it's user-actionable or not, as described above).
 - SWR puts a fetcher's throw in `error`;
-  errors from SWR should generally be re-raised inside of the React render function.
-  Sometimes SWR errors should be shown to the user instead,
+  use `useThrowingSWR` in the common case that this should be re-raised to an error boundary.
+  Sometimes SWR errors should be shown to the user instead (use the primitive `useSWR` in these cases),
   but they should not be suppressed or ignored.
+- Especially in administrative contexts, the expected/unexpected error distinction is blurry.
+  Don't let the guidelines prevent an admin from seeing useful information in the web interface.
 
 # Agent instructions
 
diff --git a/src/app/AvatarMenu.tsx b/src/app/AvatarMenu.tsx
index 49ff9434..2665ec31 100644
--- a/src/app/AvatarMenu.tsx
+++ b/src/app/AvatarMenu.tsx
@@ -5,6 +5,7 @@ import { useRouter } from 'next/navigation'
 
 import AvatarIcon from '@/app/components/AvatarIcon'
 import authClient from '@/lib/client/auth'
+import { useThrowToBoundary } from '@/lib/client/util'
 import { useConfigCtx } from '@/lib/contexts'
 import { setIsAdmin } from '@/lib/server/actions'
 
@@ -12,6 +13,7 @@ export default function AvatarMenu() {
   const session = authClient.useSession()
   const cfg = useConfigCtx()
   const router = useRouter()
+  const { throwToBoundary } = useThrowToBoundary()
 
   if (session.data) {
     const user = session.data.user
@@ -25,9 +27,10 @@ export default function AvatarMenu() {
             {user.isAdmin && <Link href='/admin'>Admin interface</Link>}
             {cfg.isDevMode && (
               <button
-                onClick={async () => {
-                  await setIsAdmin(!user.isAdmin)
-                  session.refetch()
+                onClick={() => {
+                  setIsAdmin(!user.isAdmin)
+                    .then(() => session.refetch())
+                    .catch(throwToBoundary)
                 }}
               >
                 {user.isAdmin ? '[DEV] Become non-admin' : '[DEV] Become admin'}
@@ -35,13 +38,15 @@ export default function AvatarMenu() {
             )}
             <button
               onClick={() => {
-                authClient.signOut({
-                  fetchOptions: {
-                    onSuccess: () => {
-                      router.push('/')
+                authClient
+                  .signOut({
+                    fetchOptions: {
+                      onSuccess: () => {
+                        router.push('/')
+                      },
                     },
-                  },
-                })
+                  })
+                  .catch(throwToBoundary)
               }}
             >
               Sign out
@@ -51,7 +56,15 @@ export default function AvatarMenu() {
       </>
     )
   } else if (!session.isPending && cfg.hasGithubAuth) {
-    return <button onClick={() => authClient.signIn.social({ provider: 'github' })}>Sign in via GitHub</button>
+    return (
+      <button
+        onClick={() => {
+          authClient.signIn.social({ provider: 'github' }).catch(throwToBoundary)
+        }}
+      >
+        Sign in via GitHub
+      </button>
+    )
   } else {
     return <></>
   }
diff --git a/src/app/[userName]/NewProjectForm.tsx b/src/app/[userName]/NewProjectForm.tsx
index bb660326..a3a12751 100644
--- a/src/app/[userName]/NewProjectForm.tsx
+++ b/src/app/[userName]/NewProjectForm.tsx
@@ -2,22 +2,16 @@
 
 import { useRouter } from 'next/navigation'
 import { useState } from 'react'
-import useSWR from 'swr'
 
-import { useServerAction } from '@/lib/client/util'
+import { useServerAction, useThrowingSWR } from '@/lib/client/util'
 import { formString } from '@/lib/util'
 
-import { createProject, listTemplates, type TemplateInfo } from './actions'
+import { createProject, listTemplates } from './actions'
 
 export function NewProjectForm() {
   const router = useRouter()
   const [open, setOpen] = useState(false)
-  const {
-    data: templates,
-    error: templatesError,
-    isLoading: templatesPending,
-  } = useSWR<TemplateInfo[], unknown>('listTemplates', listTemplates)
-  if (templatesError) throw templatesError
+  const { data: templates, isLoading: templatesPending } = useThrowingSWR('listTemplates', listTemplates)
 
   const [chosenTemplate, setChosenTemplate] = useState<string>('blank')
 
diff --git a/src/app/[userName]/actions.ts b/src/app/[userName]/actions.ts
index c73a6277..bceb839c 100644
--- a/src/app/[userName]/actions.ts
+++ b/src/app/[userName]/actions.ts
@@ -119,7 +119,7 @@ export const createProject = serverAction(
       await fs.rm(path.join(workspace, 'metadata.json'), { force: true })
 
       const meta = await readTemplateMetadata(templateDir)
-      packageSet = meta.packageSet
+      packageSet = meta?.packageSet
     }
 
     // Store project in DB
diff --git a/src/app/admin/components/OAuthConfig.tsx b/src/app/admin/components/OAuthConfig.tsx
index 08eb4d08..57c6b43f 100644
--- a/src/app/admin/components/OAuthConfig.tsx
+++ b/src/app/admin/components/OAuthConfig.tsx
@@ -1,15 +1,13 @@
 'use client'
 
 import { useState } from 'react'
-import useSWR from 'swr'
 
 import { fetchOAuthConfig, updateOAuthConfig } from '@/app/admin/actions'
-import { useServerAction } from '@/lib/client/util'
+import { useServerAction, useThrowingSWR } from '@/lib/client/util'
 import { formString } from '@/lib/util'
 
 export function OAuthConfig() {
-  const { data, mutate, error: oauthConfigError } = useSWR('adminOAuthConfig', () => fetchOAuthConfig())
-  if (oauthConfigError) throw oauthConfigError
+  const { data, mutate } = useThrowingSWR('adminOAuthConfig', () => fetchOAuthConfig())
 
   const [editing, setEditing] = useState(false)
 
diff --git a/src/app/forbidden.tsx b/src/app/forbidden.tsx
new file mode 100644
index 00000000..cdfa3c7d
--- /dev/null
+++ b/src/app/forbidden.tsx
@@ -0,0 +1,12 @@
+import ErrorBox from './components/ErrorBox'
+
+export default function Forbidden() {
+  return (
+    <div>
+      <h1>Not allowed</h1>
+      <ErrorBox>
+        <p>You don&apos;t have access to this page.</p>
+      </ErrorBox>
+    </div>
+  )
+}
diff --git a/src/app/page.tsx b/src/app/page.tsx
index f58485af..47375569 100644
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@@ -5,6 +5,7 @@ import Link from 'next/link'
 import { useSearchParams } from 'next/navigation'
 
 import authClient from '@/lib/client/auth'
+import { useThrowToBoundary } from '@/lib/client/util'
 import { type Config, useConfigCtx } from '@/lib/contexts'
 
 import ErrorBox from './components/ErrorBox'
@@ -31,6 +32,7 @@ export default function Root() {
   const cfg = useConfigCtx()
   const session = authClient.useSession()
   const error = useSearchParams().get('error')
+  const { throwToBoundary } = useThrowToBoundary()
 
   return (
     <>
@@ -53,9 +55,7 @@ export default function Root() {
             disabled={!cfg.hasGithubAuth}
             title={!cfg.hasGithubAuth ? 'Ask your administrator to set up GitHub authentication.' : undefined}
             onClick={() => {
-              authClient.signIn.social({
-                provider: 'github',
-              })
+              authClient.signIn.social({ provider: 'github' }).catch(throwToBoundary)
             }}
           >
             GitHub
@@ -67,8 +67,10 @@ export default function Root() {
                 const email = 'dev@dev.localhost'
                 const name = 'dev'
                 const password = 'dev'
-                await authClient.signUp.email({ email, name, password })
-                await authClient.signIn.email({ email, password })
+                authClient.signUp
+                  .email({ email, name, password })
+                  .then(() => authClient.signIn.email({ email, password }))
+                  .catch(throwToBoundary)
               }}
             >
               [DEV]
diff --git a/src/app/setup/page.tsx b/src/app/setup/page.tsx
index b922020c..dc3ef669 100644
--- a/src/app/setup/page.tsx
+++ b/src/app/setup/page.tsx
@@ -3,10 +3,9 @@
 import Link from 'next/link'
 import { redirect } from 'next/navigation'
 import { useEffect, useRef, useState } from 'react'
-import useSWR from 'swr'
 import { z } from 'zod'
 
-import { useServerAction } from '@/lib/client/util'
+import { useServerAction, useThrowingSWR, useThrowToBoundary } from '@/lib/client/util'
 import { useConfigCtx } from '@/lib/contexts'
 import { LEAN_VERSION_RE, SeedEvent, zSeedEvent } from '@/lib/util'
 
@@ -37,9 +36,7 @@ export default function Setup() {
   const [progress, setProgress] = useState({ pct: 0, label: '' })
   const [logs, setLogs] = useState<string[]>([])
   const [leanVersion, setLeanVersion] = useState<string | undefined>()
-  const { data: leanVersions, error: leanVersionsError } = useSWR('leanVersions', fetchLeanVersions)
-  if (leanVersionsError) throw leanVersionsError
-
+  const { data: leanVersions } = useThrowingSWR('leanVersions', fetchLeanVersions)
   const logRef = useRef<HTMLDivElement>(null)
 
   const [configError, saveConfigAction, savingConfig] = useServerAction(
@@ -48,13 +45,14 @@ export default function Setup() {
   )
 
   // Sync with server state on mount (handles page reload during seeding).
+  const { throwToBoundary } = useThrowToBoundary()
   useEffect(() => {
     fetchSetupStatus().then(status => {
       if (status.configSaved) setConfigSaved(true)
       if (status.seeded) setPhase('done')
       else if (status.seeding) setPhase('seeding')
-    })
-  }, [])
+    }, throwToBoundary)
+  }, [throwToBoundary])
 
   // Auto-scroll log area.
   useEffect(() => {
diff --git a/src/app/unauthorized.tsx b/src/app/unauthorized.tsx
new file mode 100644
index 00000000..d3ceeaac
--- /dev/null
+++ b/src/app/unauthorized.tsx
@@ -0,0 +1,12 @@
+import ErrorBox from './components/ErrorBox'
+
+export default function Unauthorized() {
+  return (
+    <div>
+      <h1>Unauthorized</h1>
+      <ErrorBox>
+        <p>You need to be signed in to access this page.</p>
+      </ErrorBox>
+    </div>
+  )
+}
diff --git a/src/lib/client/auth.ts b/src/lib/client/auth.ts
index fab5d513..01b773f5 100644
--- a/src/lib/client/auth.ts
+++ b/src/lib/client/auth.ts
@@ -4,6 +4,8 @@ import { createAuthClient } from 'better-auth/react'
 import type { AuthInstance } from '@/lib/server/auth'
 
 export default createAuthClient({
+  // connection errors always throw, this makes non-ok status throw as well so they can be handled similarly
+  fetchOptions: { throw: true },
   // https://better-auth.com/docs/concepts/typescript#inferring-additional-fields-on-client
   plugins: [inferAdditionalFields<AuthInstance>()],
 })
diff --git a/src/lib/client/util.ts b/src/lib/client/util.ts
index 5a083365..bcf9770e 100644
--- a/src/lib/client/util.ts
+++ b/src/lib/client/util.ts
@@ -1,6 +1,7 @@
-import { useActionState } from 'react'
+import { useActionState, useState } from 'react'
+import useSWR, { type Key, type SWRConfiguration } from 'swr'
 
-import type { ActionResponse } from '@/lib/util'
+import { type ActionResponse, unknownAsError } from '@/lib/util'
 
 /** Returns `[error, dispatchAction, pending]`. */
 export function useServerAction<Payload = void, T = void>(
@@ -14,3 +15,28 @@ export function useServerAction<Payload = void, T = void>(
     return null
   }, null)
 }
+
+/**
+ * Creates a callback that will throw from the render phase.
+ * In a callback, `foo().then(bar)` might silently ignore errors;
+ * whereas `foo().then(bar).catch(rethrow)` will ensure the error is thrown to an error boundary.
+ */
+export function useThrowToBoundary(): { throwToBoundary: (error: unknown) => void } {
+  const [error, setError] = useState<unknown>()
+  if (error !== undefined) {
+    throw unknownAsError(error)
+  }
+  return { throwToBoundary: setError }
+}
+
+/**
+ * Wraps useSWR hook to ensure that any error thrown in the handler will be thrown
+ * to the closest error boundary.
+ */
+export function useThrowingSWR<T>(key: Key, fetcher: () => Promise<T>, config?: SWRConfiguration<T, unknown>) {
+  const result = useSWR<T, unknown>(key, fetcher, config)
+  if (result.error) {
+    throw unknownAsError(result.error)
+  }
+  return result
+}
diff --git a/src/lib/util.ts b/src/lib/util.ts
index 9a414e50..abe06e27 100644
--- a/src/lib/util.ts
+++ b/src/lib/util.ts
@@ -43,3 +43,6 @@ export function formString(formData: FormData, name: string): string {
   if (typeof value === 'string') return value
   throw new Error(`form field '${name}' is a File unexpectedly`)
 }
+
+/** Ensure that an unknown has the form of an Error by wrapping it if appropriate */
+export const unknownAsError = (e: unknown) => (e instanceof Error ? e : new Error(String(e)))

From 18868c17a3c84bb52b82039522bb52177d84520c Mon Sep 17 00:00:00 2001
From: Rob Simmons <robsimmons@gmail.com>
Date: Fri, 7 Aug 2026 15:36:16 -0400
Subject: [PATCH 3/7]

---
 src/lib/client/util.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/lib/client/util.ts b/src/lib/client/util.ts
index bcf9770e..838b03b0 100644
--- a/src/lib/client/util.ts
+++ b/src/lib/client/util.ts
@@ -34,8 +34,10 @@ export function useThrowToBoundary(): { throwToBoundary: (error: unknown) => voi
  * to the closest error boundary.
  */
 export function useThrowingSWR<T>(key: Key, fetcher: () => Promise<T>, config?: SWRConfiguration<T, unknown>) {
-  const result = useSWR<T, unknown>(key, fetcher, config)
-  if (result.error) {
+  const result = useSWR<T, unknown>(key, () => fetcher(), config)
+  // On a background revalidation (like when the window refocuses), result.data will be defined
+  // Don't throw if such a background revalidation fails, just continue returning the (stale) data.
+  if (result.error && result.data === undefined) {
     throw unknownAsError(result.error)
   }
   return result

From 55acb29b057ff776b4b799459e2f24aa38e34bda Mon Sep 17 00:00:00 2001
From: Rob Simmons <robsimmons@gmail.com>
Date: Fri, 7 Aug 2026 16:37:27 -0400
Subject: [PATCH 4/7] move dev signup to server, have dev button automatically
 sign in

---
 src/app/components/ErrorBox.tsx |  2 +-
 src/app/page.tsx                |  6 +-----
 src/lib/client/util.ts          |  7 +++++--
 src/lib/server/auth.ts          | 12 +++++++++++-
 4 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/src/app/components/ErrorBox.tsx b/src/app/components/ErrorBox.tsx
index 418c6104..d5f624df 100644
--- a/src/app/components/ErrorBox.tsx
+++ b/src/app/components/ErrorBox.tsx
@@ -1,4 +1,4 @@
-export default function Error({ children }: { children: React.ReactNode }) {
+export default function ErrorBox({ children }: { children: React.ReactNode }) {
   return (
     <div
       style={{
diff --git a/src/app/page.tsx b/src/app/page.tsx
index 47375569..530b2676 100644
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@@ -65,12 +65,8 @@ export default function Root() {
               className='login-link'
               onClick={async () => {
                 const email = 'dev@dev.localhost'
-                const name = 'dev'
                 const password = 'dev'
-                authClient.signUp
-                  .email({ email, name, password })
-                  .then(() => authClient.signIn.email({ email, password }))
-                  .catch(throwToBoundary)
+                authClient.signIn.email({ email, password }).catch(throwToBoundary)
               }}
             >
               [DEV]
diff --git a/src/lib/client/util.ts b/src/lib/client/util.ts
index 838b03b0..e8a6d236 100644
--- a/src/lib/client/util.ts
+++ b/src/lib/client/util.ts
@@ -37,8 +37,11 @@ export function useThrowingSWR<T>(key: Key, fetcher: () => Promise<T>, config?:
   const result = useSWR<T, unknown>(key, () => fetcher(), config)
   // On a background revalidation (like when the window refocuses), result.data will be defined
   // Don't throw if such a background revalidation fails, just continue returning the (stale) data.
-  if (result.error && result.data === undefined) {
-    throw unknownAsError(result.error)
+  if (result.error !== undefined) {
+    if (result.data === undefined) {
+      throw unknownAsError(result.error)
+    }
+    console.error(`Background revalidation failed for ${key}, reusing old value`, result.error)
   }
   return result
 }
diff --git a/src/lib/server/auth.ts b/src/lib/server/auth.ts
index bdaeb7ab..68a6dcee 100644
--- a/src/lib/server/auth.ts
+++ b/src/lib/server/auth.ts
@@ -37,7 +37,7 @@ async function createAuth() {
     await saveConfig()
   }
 
-  return betterAuth({
+  const auth = betterAuth({
     database: prismaAdapter(getDb(), { provider: 'sqlite' }),
     secret: config.authSessionSecret,
     databaseHooks: {
@@ -101,6 +101,16 @@ async function createAuth() {
     },
     plugins: [nextCookies()],
   })
+
+  if (isDevMode()) {
+    const email = 'dev@dev.localhost'
+    const existing = await getDb().user.findUnique({ where: { email } })
+    if (!existing) {
+      await auth.api.signUpEmail({ body: { email, name: 'dev', password: 'dev' } })
+    }
+  }
+
+  return auth
 }
 
 export type AuthInstance = Awaited<ReturnType<typeof createAuth>>

From bad5f09e76c052f3d938c42a64acc6e147709525 Mon Sep 17 00:00:00 2001
From: "Robert J. Simmons" <442315+robsimmons@users.noreply.github.com>
Date: Sat, 8 Aug 2026 20:35:43 -0400
Subject: [PATCH 5/7] Update src/app/[userName]/actions.ts

Co-authored-by: Wojciech Nawrocki <13901751+Vtec234@users.noreply.github.com>
---
 src/app/[userName]/actions.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/app/[userName]/actions.ts b/src/app/[userName]/actions.ts
index bceb839c..1acfd278 100644
--- a/src/app/[userName]/actions.ts
+++ b/src/app/[userName]/actions.ts
@@ -24,7 +24,7 @@ type TemplateMetadata = z.infer<typeof zTemplateMetadata>
 
 /**
  * Read `metadata.json` from `templateDir`,
- * raising an exception if the file is missing or does not work.
+ * raising an exception if the file is missing or unparseable.
  */
 async function readTemplateMetadata(templateDir: string): Promise<TemplateMetadata> {
   const metaPath = path.join(templateDir, 'metadata.json')

From 7379f49787dde914a076a0c07200924ea4c8f2e6 Mon Sep 17 00:00:00 2001
From: "Robert J. Simmons" <442315+robsimmons@users.noreply.github.com>
Date: Sat, 8 Aug 2026 20:36:00 -0400
Subject: [PATCH 6/7] Update src/app/[userName]/actions.ts

Co-authored-by: Wojciech Nawrocki <13901751+Vtec234@users.noreply.github.com>
---
 src/app/[userName]/actions.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/app/[userName]/actions.ts b/src/app/[userName]/actions.ts
index 1acfd278..6f748388 100644
--- a/src/app/[userName]/actions.ts
+++ b/src/app/[userName]/actions.ts
@@ -60,7 +60,7 @@ export async function listTemplates(): Promise<TemplateInfo[]> {
     try {
       meta = await readTemplateMetadata(path.join(entry.parentPath, entry.name))
     } catch (err) {
-      console.error(`Skipping ${entry.name} due to metadata error`, err)
+      console.error(`Skipping template '${entry.name}' due to metadata error`, err)
       continue
     }
     result.push({

From c08194b1fea4d29820bd33f3ade53eaf28a5cd5b Mon Sep 17 00:00:00 2001
From: "Robert J. Simmons" <442315+robsimmons@users.noreply.github.com>
Date: Sat, 8 Aug 2026 20:43:17 -0400
Subject: [PATCH 7/7] Update src/app/error.tsx

Co-authored-by: Wojciech Nawrocki <13901751+Vtec234@users.noreply.github.com>
---
 src/app/error.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/app/error.tsx b/src/app/error.tsx
index 7686d2e2..21725d48 100644
--- a/src/app/error.tsx
+++ b/src/app/error.tsx
@@ -24,6 +24,7 @@ export default function ErrorBoundary({ error, retry }: ErrorBoundaryProps) {
     <div>
       <h1>Something went wrong!</h1>
       <ErrorBox>
+        {/* digest is only present in server-side errors */}
         {error.digest && (
           <p>
             Something went wrong on the server. Try again, or contact your administrator with the error code{' '}