TanStack Start: Server Function Error Handling Patterns

TL;DR: Server Functions in TanStack Start benötigen eine strukturierte Fehlerbehandlung. Dieser Guide behandelt Zod-Validierungsfehler-Mapping, typisierte Fehlerantworten, die Typsicherheit über die Netzwerkgrenze hinweg bewahren, Fehlergruppierung für das Monitoring und clientseitige Recovery-Muster.

Einführung

TanStack Start Server Functions bilden die Brücke zwischen Client und Server. Wenn ein Fehler auf dem Server auftritt, muss er auf strukturierte Weise an den Client weitergegeben werden. Die Herausforderung besteht darin, die Typsicherheit über die Netzwerkgrenze hinweg aufrechtzuerhalten und gleichzeitig nützliche Fehlerinformationen bereitzustellen.

Typisierte Fehlerantworten

Um die Typsicherheit über die Client-Server-Grenze hinweg zu gewährleisten, definieren Sie eine diskriminierte Union für Ihre Fehlertypen. So erstellen Sie ein typisiertes Fehlersystem, das Validierungs-, Authentifizierungs-, Not-Found- und Serverfehler abdeckt:

import { createServerFn } from '@tanstack/react-start'
import { z } from 'zod'

type ApiError =
  | { type: 'validation'; fields: Record<string, string[]> }
  | { type: 'not_found'; resource: string }
  | { type: 'auth'; message: string }
  | { type: 'server'; retryAfter: number }

export const updateProfileFn = createServerFn({ method: 'POST' })
  .validator(z.object({
    name: z.string().min(2),
    email: z.string().email(),
  }))
  .handler(async ({ data }): Promise<{ success: true } | ApiError> => {
    try {
      await db.updateUser(data)
      return { success: true }
    } catch (error) {
      return { type: 'server', retryAfter: 30 }
    }
  })

Der Rückgabetyp { success: true } | ApiError ist vollständig typsicher. Auf der Clientseite zwingt TypeScript Sie dazu, jeden Fall zu behandeln – was unbehandelte Fehlerpfade in der Produktion verhindert.

Clientsseitige Fehlerbehandlung

Auf der Clientseite prüft der Mutation-Handler, ob das Ergebnis ein Fehler oder ein Erfolg ist. Die Verwendung eines Type-Narrowing-Musters hält den Fehlerbehandlungszweig klar und wartbar:

const mutation = useMutation({
  mutationFn: updateProfileFn,
  onSuccess: (result) => {
    if ('type' in result) {
      // Strukturierten Fehler behandeln
      if (result.type === 'validation') {
        // Feldfehler setzen
      }
      if (result.type === 'auth') {
        router.navigate({ to: '/login' })
      }
      return
    }
    // Erfolg
    toast.success('Profil aktualisiert')
  },
})

Die clientsseitige Logik behandelt jeden Fehlertyp mit passender UX: Validierungsfehler zeigen Inline-Feldmeldungen an, Authentifizierungsfehler leiten zum Login weiter, und Serverfehler lösen Retry-Flows aus – alles bei vollständiger Wahrung der Typsicherheit.

Entscheidungshilfe für Fehlertypen

Fazit

Typisierte Fehlerantworten in TanStack Start Server Functions ermöglichen typsichere Fehlerbehandlung über die Netzwerkgrenze hinweg. Dieses Muster verwandelt kryptische Server-Abstürze in umsetzbare, clientsseitige Recovery-Flows. Für eine umfassende Fehlerbehandlung empfiehlt es sich, diesen Ansatz mit Error Boundaries für route-basierte Error-UI, Middleware und Request Lifecycle für zentralisiertes Error-Logging und SaaS Monitoring und Observability für Production Error Tracking und Alerting zu kombinieren.