App crashes on form submission errors despite error handling

[jason-ezenwa]

Description

The application crashes when form submission encounters errors, even though error handling is implemented. This occurs despite having proper try-catch blocks and TanStack Query error handling.

Expected Behavior

• Form submission errors should display toast notifications
• App should remain stable and functional
• Users should be able to retry form submission

Current Behavior

• Toast error messages appear
• But the app crashes/breaks after the error
• Console shows error propagation down to onSubmit function, despite catch blocks

i am using v5.90.6

const createJourneyMutation = useMutation({
    mutationFn: async (data: JourneyFormData & { resumeFile: File }) => {
      // Create FormData like the playground
      const formData = new FormData();
      formData.append("companyName", data.companyName);
      formData.append("jobTitle", data.jobTitle);
      formData.append("jobDescription", data.jobDescription);
      formData.append("resume", data.resumeFile);

      const response = await fetch("/api/journeys", {
        method: "POST",
        body: formData,
      });

      if (!response.ok) {
        const errorData = await response.json();
        throw new Error(errorData.error || "Failed to create application");
      }

      return response.json();
    },
    onError: (error) => {
      console.error("onError error: Failed to create journey:", error);
      toast.error(error.message);
    },
  });

  const onSubmit = async (data: JourneyFormData) => {
    try {
      if (!resumeFile) {
        toast.error("Please upload a resume");
        return;
      }

      createJourneyMutation.mutate({
        ...data,
        resumeFile,
      });
    } catch (error) {
      console.error("propagation error: Failed to create journey:", error);
    }
  };

[zisam-glitch]

Hi @jason-ezenwa,

This crash happens due to a combination of how TanStack Query handles errors, asynchronous Promise semantics, and response parsing. Here is a diagnosis of the root causes and how to fix them.

---

1. Root Causes

A. mutate vs mutateAsync and try...catch

In TanStack Query, createJourneyMutation.mutate(...) is fire-and-forget (it returns void). It does not return a rejecting Promise to the caller:

// ❌ try...catch does NOTHING here because mutate() does not return a Promise
try {
  createJourneyMutation.mutate({ ...data, resumeFile });
} catch (error) {
  // This catch block will NEVER execute for mutation errors
}

Any error thrown inside mutationFn is captured internally by TanStack Query and sent to its onError callback and internal state (isError, error).

• If you want to handle the error flow sequentially with try...catch inside onSubmit, you must use await createJourneyMutation.mutateAsync(...).
• Conversely, if mutateAsync was called anywhere without await or .catch(), the unhandled rejected Promise will bubble up to window.onunhandledrejection and can crash dev overlays or test runners.

B. throwOnError Bubbling to React Error Boundaries

The symptom "toast error messages appear, but the app crashes/breaks after the error" strongly indicates that throwOnError: true is active (either globally on QueryClient defaultOptions.mutations.throwOnError or inherited from query defaults).

• In TanStack Query v5, when throwOnError: true is enabled on mutations, the library re-throws the mutation error during the React component render phase to hand it over to a React <ErrorBoundary>.
• If your component tree is not wrapped in an Error Boundary, React unmounts the entire component tree, leading to a blank screen / application crash.

C. response.json() Crash on 500 / 413 / 502 HTML Responses

When uploading files (like resumeFile), servers or reverse proxies (e.g. Next.js, Vercel, Nginx) often return HTML or plain text instead of JSON when errors occur (such as 413 Payload Too Large, 504 Gateway Timeout, or unhandled server crashes).

if (!response.ok) {
  const errorData = await response.json(); // 💥 Throws SyntaxError: Unexpected token '<'...
  throw new Error(errorData.error || "Failed to create application");
}

Calling await response.json() on an HTML error response throws a SyntaxError, which obscures the real server error and can disrupt error handlers.

D. Native <form onSubmit> Default Event

If onSubmit is attached directly to <form onSubmit={onSubmit}> rather than through React Hook Form's handleSubmit:

• The first argument received by onSubmit is a React.FormEvent, not JourneyFormData.
• If e.preventDefault() is omitted, the browser attempts a native HTTP POST submission and refreshes/crashes the page right after the toast pops up.

---

2. Solutions

Option 1: Idiomatic TanStack Query Pattern (Recommended)

Use .mutate() with callbacks. Do not wrap in try...catch, and ensure throwOnError: false on the mutation.

import { useMutation } from "@tanstack/react-query";
import { toast } from "sonner"; // or your toast library

// Helper to safely extract error messages even if server returns HTML
async function parseErrorResponse(response: Response): Promise<string> {
  try {
    const contentType = response.headers.get("content-type");
    if (contentType && contentType.includes("application/json")) {
      const data = await response.json();
      return data.error || data.message || `Request failed with status ${response.status}`;
    }
    const text = await response.text();
    return text || `Request failed with status ${response.status}`;
  } catch {
    return `Server error (${response.status})`;
  }
}

export function JourneyForm() {
  const createJourneyMutation = useMutation({
    mutationFn: async (data: JourneyFormData & { resumeFile: File }) => {
      const formData = new FormData();
      formData.append("companyName", data.companyName);
      formData.append("jobTitle", data.jobTitle);
      formData.append("jobDescription", data.jobDescription);
      formData.append("resume", data.resumeFile);

      const response = await fetch("/api/journeys", {
        method: "POST",
        body: formData,
      });

      if (!response.ok) {
        const errorMessage = await parseErrorResponse(response);
        throw new Error(errorMessage);
      }

      return response.json();
    },
    // Explicitly prevent bubbling to React Error Boundary
    throwOnError: false,
    onSuccess: (data) => {
      toast.success("Application created successfully!");
    },
    onError: (error: Error) => {
      console.error("Mutation failed:", error.message);
      toast.error(error.message);
    },
  });

  const onSubmit = (data: JourneyFormData) => {
    if (!resumeFile) {
      toast.error("Please upload a resume");
      return;
    }

    // .mutate is fire-and-forget: callbacks handle success and error
    createJourneyMutation.mutate({
      ...data,
      resumeFile,
    });
  };

  return (
    // If using react-hook-form: onSubmit={handleSubmit(onSubmit)}
    // If using native form: onSubmit={(e) => { e.preventDefault(); onSubmit(formData); }}
    <form onSubmit={handleSubmit(onSubmit)}>
      {/* Inputs */}
      <button 
        type="submit" 
        disabled={createJourneyMutation.isPending}
      >
        {createJourneyMutation.isPending ? "Submitting..." : "Submit"}
      </button>
    </form>
  );
}

---

Option 2: Promise Pattern with mutateAsync and try...catch

If you prefer handling flow sequentially in onSubmit, use await mutateAsync(...) inside try...catch:

const onSubmit = async (data: JourneyFormData) => {
  if (!resumeFile) {
    toast.error("Please upload a resume");
    return;
  }

  try {
    const result = await createJourneyMutation.mutateAsync({
      ...data,
      resumeFile,
    });
    
    toast.success("Application created successfully!");
    // navigate or reset form here
  } catch (error) {
    // mutateAsync rejects on error, so it IS caught here
    console.error("Caught in onSubmit:", error);
    toast.error(error instanceof Error ? error.message : "An unexpected error occurred");
  }
};

Note: When using Option 2, avoid adding a duplicate onError callback in useMutation that also calls toast.error, otherwise two toast notifications will be triggered for a single failure.

---

Summary Checklist

1. Use mutate without try...catch, OR use await mutateAsync with try...catch.
2. Set throwOnError: false unless you have a dedicated <ErrorBoundary> component intended to catch and replace your form UI on failure.
3. Safely parse non-JSON responses so that 413/500 HTML error pages don't throw parsing SyntaxErrors.
4. Ensure e.preventDefault() is executed on form submission.