types: improve type safety in error handling — replace as-casts with type guards (#4638)

`catch` bindings and query `error` fields are `unknown` — the thrower picks
the shape. Nine sites asserted one anyway (`(error as Error).message`,
`error as Error`, `error as { status?: number }`), so a thrown string gave
`undefined` where a string was expected and a thrown `null` crashed the
handler that was meant to report it.

Replaces those assertions with structural narrowing: `getErrorMessage` in
web's `errorHandling.ts`, `toError`/`messageOf` local to mobile's
WebSocketManager, and inline guards where a single site reads a single field.

The one behavior difference is on inputs that already misbehaved: a thrown
`null` now falls through to the retry path instead of throwing a TypeError
inside the catch block.

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: 3 people

mobile/src/components/graph_editor/PropertyField.tsx

@@ -969,8 +969,11 @@ const JSONWidget: React.FC<{
   colors: ThemeColors;
 }> = ({ prop, value, onChange, colors }) => {
   const dataStr =
-    typeof value === "object" && value !== null
-      ? (value as Record<string, unknown>).data as string | undefined
+    typeof value === "object" &&
+    value !== null &&
+    "data" in value &&
+    typeof value.data === "string"
+      ? value.data
       : typeof value === "string"
         ? value
         : undefined;
@@ -983,7 +986,7 @@ const JSONWidget: React.FC<{
       JSON.parse(localValue);
       setError(null);
     } catch (e) {
-      setError((e as Error).message);
+      setError(e instanceof Error ? e.message : "Invalid JSON");
     }
     onChange({ type: "json", data: localValue });
   }, [localValue, onChange]);

mobile/src/hooks/useApplications.ts

@@ -33,6 +33,14 @@ import {
 import { trpc } from '../trpc/client';
 import type { Workflow } from '../types/workflow';
 
+/** tRPC types its `error` as a plain interface, not an `Error` subtype. */
+function toError(error: { message: string } | null): Error | null {
+  if (!error) {
+    return null;
+  }
+  return error instanceof Error ? error : new Error(error.message);
+}
+
 export const applicationKeys = {
   all: ['applications'] as const,
   list: (projectId?: string): QueryKey => [
@@ -187,10 +195,6 @@ export function useApplicationApp(id: string | undefined): ApplicationApp {
       application.isLoading ||
       release.isLoading ||
       (Boolean(workflowId) && !pinned && liveWorkflow.isLoading),
-    error:
-      (application.error as Error | null) ??
-      (release.error as Error | null) ??
-      (liveWorkflow.error as Error | null) ??
-      null,
+    error: application.error ?? release.error ?? toError(liveWorkflow.error),
   };
 }

mobile/src/queryClient.ts

@@ -31,12 +31,17 @@ function httpStatusFromError(error: unknown): number | undefined {
   if (typeof error !== 'object' || error === null) {
     return undefined;
   }
-  const e = error as { status?: unknown; data?: { httpStatus?: unknown } };
-  if (typeof e.status === 'number') {
-    return e.status;
+  if ('status' in error && typeof error.status === 'number') {
+    return error.status;
   }
-  if (typeof e.data?.httpStatus === 'number') {
-    return e.data.httpStatus;
+  if (
+    'data' in error &&
+    typeof error.data === 'object' &&
+    error.data !== null &&
+    'httpStatus' in error.data &&
+    typeof error.data.httpStatus === 'number'
+  ) {
+    return error.data.httpStatus;
   }
   return undefined;
 }

mobile/src/services/WebSocketManager.ts

@@ -18,6 +18,24 @@ import { isAppForeground, subscribeAppLifecycle } from '../hooks/useAppLifecycle
 
 type WebSocketMessage = { type: string };
 
+/** The message an unknown thrown value or error event carries, or `fallback`. */
+function messageOf(value: unknown, fallback: string): string {
+  return typeof value === 'object' &&
+    value !== null &&
+    'message' in value &&
+    typeof value.message === 'string' &&
+    value.message
+    ? value.message
+    : fallback;
+}
+
+/** A `catch` binding is `unknown` — narrow it rather than assert it. */
+function toError(thrown: unknown, fallback: string): Error {
+  return thrown instanceof Error
+    ? thrown
+    : new Error(messageOf(thrown, fallback));
+}
+
 interface WebSocketCallbacks {
   onStateChange?: (state: ConnectionState, previousState: ConnectionState) => void;
   onMessage?: (data: WebSocketMessageData) => void;
@@ -250,7 +268,7 @@ export class WebSocketManager {
       this.ws!.send(encoded);
     } catch (error) {
       console.error('Failed to send message:', error);
-      this.callbacks.onError?.(error as Error);
+      this.callbacks.onError?.(toError(error, 'Failed to send message'));
       throw error;
     }
   }
@@ -260,7 +278,7 @@ export class WebSocketManager {
 
     this.ws.onopen = () => this.handleOpen();
     this.ws.onmessage = (event) => this.handleMessage(event);
-    this.ws.onerror = (event) => this.handleError(event as { message?: string });
+    this.ws.onerror = (event) => this.handleError(event);
     this.ws.onclose = (event) => this.handleClose(event);
   }
 
@@ -319,7 +337,7 @@ export class WebSocketManager {
       this.callbacks.onMessage?.(data as WebSocketMessageData);
     } catch (error) {
       console.error('Failed to process message:', error);
-      this.callbacks.onError?.(error as Error);
+      this.callbacks.onError?.(toError(error, 'Failed to process message'));
     }
   }
 
@@ -354,9 +372,11 @@ export class WebSocketManager {
     });
   }
 
-  private handleError(event: { message?: string }): void {
+  private handleError(event: unknown): void {
     console.error('WebSocket error:', event);
-    this.callbacks.onError?.(new Error(event.message || 'WebSocket error occurred'));
+    this.callbacks.onError?.(
+      new Error(messageOf(event, 'WebSocket error occurred'))
+    );
   }
 
   private handleClose(event: WebSocketCloseEvent): void {
@@ -494,7 +514,7 @@ export class WebSocketManager {
         this.setupEventHandlers();
         this.startConnectionTimeout();
       } catch (error) {
-        this.handleConnectionError(error as Error);
+        this.handleConnectionError(toError(error, 'Failed to open WebSocket'));
         reject(error);
       }
     });
@@ -663,7 +683,7 @@ export class WebSocketManager {
         this.send(message);
       } catch (error) {
         console.error('Failed to send queued message:', error);
-        this.callbacks.onError?.(error as Error);
+        this.callbacks.onError?.(toError(error, 'Failed to send queued message'));
       }
     }
   }

web/src/components/script/ScriptLineRow.tsx

@@ -39,6 +39,7 @@ import {
 import { voiceLine } from "../../stores/script/scriptVoicing";
 import { useAssetStore } from "../../stores/AssetStore";
 import { getAssetUrl } from "../../utils/assetHelpers";
+import { getErrorMessage } from "../../utils/errorHandling";
 import ScriptTakeGallery from "./ScriptTakeGallery";
 
 /**
@@ -195,7 +196,7 @@ const ScriptLineRow = ({
     try {
       await voiceLine(scriptId, line.id);
     } catch (error) {
-      setVoiceError((error as Error).message ?? "Voicing failed");
+      setVoiceError(getErrorMessage(error, "Voicing failed"));
     }
   }, [scriptId, line.id]);
 

web/src/hooks/script/useScriptServerSync.ts

@@ -17,6 +17,7 @@ import {
   type ScriptDraft,
   type ScriptSaveStatus
 } from "../../stores/script/ScriptStore";
+import { getErrorMessage } from "../../utils/errorHandling";
 
 const AUTOSAVE_DEBOUNCE_MS = 750;
 const RETRY_DELAY_MS = 5_000;
@@ -43,9 +44,7 @@ const responseToScript = (
 };
 
 const isNotFound = (error: unknown): boolean =>
-  !!error &&
-  typeof error === "object" &&
-  /not found/i.test((error as Error).message ?? "");
+  /not found/i.test(getErrorMessage(error));
 
 export const useScriptServerSync = (scriptId: string): void => {
   const utils = trpc.useUtils();
@@ -162,7 +161,7 @@ export const useScriptServerSync = (scriptId: string): void => {
           store.getState().setSaveStatus(scriptId, "error");
           return;
         }
-        if (/modified since last read/i.test((error as Error).message ?? "")) {
+        if (/modified since last read/i.test(getErrorMessage(error))) {
           // Set "reloaded" only after the server copy is applied, not before.
           await load("reloaded");
         } else {

web/src/hooks/storyboard/useStoryboardServerSync.ts

@@ -16,6 +16,7 @@ import {
   type StoryboardBoard
 } from "../../stores/storyboard/StoryboardStore";
 import type { Screenplay, Shot } from "@nodetool-ai/protocol";
+import { getErrorMessage } from "../../utils/errorHandling";
 
 const AUTOSAVE_DEBOUNCE_MS = 750;
 const RETRY_DELAY_MS = 5_000;
@@ -61,9 +62,7 @@ const responseToBoard = (
 };
 
 const isNotFound = (error: unknown): boolean =>
-  !!error &&
-  typeof error === "object" &&
-  /not found/i.test((error as Error).message ?? "");
+  /not found/i.test(getErrorMessage(error));
 
 export const useStoryboardServerSync = (boardId: string): void => {
   const utils = trpc.useUtils();
@@ -139,7 +138,7 @@ export const useStoryboardServerSync = (boardId: string): void => {
       } catch (error) {
         if (disposed) return;
         console.error("Storyboard autosave failed", error);
-        if (/modified since last read/i.test((error as Error).message ?? "")) {
+        if (/modified since last read/i.test(getErrorMessage(error))) {
           // CAS conflict: the server copy wins.
           await load();
         } else {

web/src/stores/AssetStore.ts

@@ -144,7 +144,13 @@ const uploadAsset = async (
     emitUploadProgress(onUploadProgress, total, total);
     return normalizeAssetUrls(data as Asset);
   } catch (error) {
-    const statusCode = (error as { status?: number })?.status;
+    const statusCode =
+      typeof error === "object" &&
+      error !== null &&
+      "status" in error &&
+      typeof error.status === "number"
+        ? error.status
+        : undefined;
     const normalizedError =
       error instanceof DOMException && error.name === "AbortError"
         ? createErrorMessage(error, "Asset upload was cancelled")

web/src/utils/errorHandling.ts

@@ -5,6 +5,16 @@ export class AppError extends Error {
   }
 }
 
+const hasErrorMessage = (error: unknown): error is { message: string } =>
+  typeof error === "object" &&
+  error !== null &&
+  "message" in error &&
+  typeof error.message === "string";
+
+/** The message of a thrown value, or `fallback` when it carries none. */
+export const getErrorMessage = (error: unknown, fallback = ""): string =>
+  hasErrorMessage(error) ? error.message : fallback;
+
 export const createErrorMessage = (
   error: unknown,
   defaultMessage: string