feat: enhance toast error messages with structured parsing

- Add parseErrorMessage() utility to parse JSON error responses
- Add showErrorToast() helper for consistent error display
- Update all toast.error calls to use structured error parsing
- Support multiple error formats: error+troubleshooting, title+description, message+details
- Enhance apiRequest() to support both 'body' and 'data' properties
- Add comprehensive unit tests for error parsing functionality
- Improve user experience with clear, actionable error messages

Fixes structured error messages from Gitea API responses that were showing as raw JSON

package.json

@@ -1,7 +1,7 @@
 {
   "name": "gitea-mirror",
   "type": "module",
-  "version": "2.9.1",
+  "version": "2.9.3",
   "engines": {
     "bun": ">=1.2.9"
   },

src/components/activity/ActivityLog.tsx

@@ -16,7 +16,7 @@ import {
   DialogTitle,
   DialogTrigger,
 } from '../ui/dialog';
-import { apiRequest, formatDate } from '@/lib/utils';
+import { apiRequest, formatDate, showErrorToast } from '@/lib/utils';
 import { useAuth } from '@/hooks/useAuth';
 import type { MirrorJob } from '@/lib/db/schema';
 import type { ActivityApiResponse } from '@/types/activities';
@@ -155,7 +155,7 @@ export function ActivityLog() {
       if (!res.success) {
         // Only show error toast for manual refreshes to avoid spam during live updates
         if (!isLiveRefresh) {
-          toast.error(res.message ?? 'Failed to fetch activities.');
+          showErrorToast(res.message ?? 'Failed to fetch activities.', toast);
         }
         return false;
       }
@@ -184,9 +184,7 @@ export function ActivityLog() {
       if (isMountedRef.current) {
         // Only show error toast for manual refreshes to avoid spam during live updates
         if (!isLiveRefresh) {
-          toast.error(
-            err instanceof Error ? err.message : 'Failed to fetch activities.',
-          );
+          showErrorToast(err, toast);
         }
       }
       return false;
@@ -331,11 +329,11 @@ export function ActivityLog() {
         setActivities([]);
         toast.success(`All activities cleaned up successfully. Deleted ${res.result.mirrorJobsDeleted} mirror jobs and ${res.result.eventsDeleted} events.`);
       } else {
-        toast.error(res.error || 'Failed to cleanup activities.');
+        showErrorToast(res.error || 'Failed to cleanup activities.', toast);
       }
     } catch (error) {
       console.error('Error cleaning up activities:', error);
-      toast.error(error instanceof Error ? error.message : 'Failed to cleanup activities.');
+      showErrorToast(error, toast);
     } finally {
       setIsInitialLoading(false);
     }

src/components/auth/LoginForm.tsx

@@ -6,6 +6,7 @@ import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '@/components/ui/card';
 import { SiGitea } from 'react-icons/si';
 import { toast, Toaster } from 'sonner';
+import { showErrorToast } from '@/lib/utils';
 import { FlipHorizontal } from 'lucide-react';
 
 export function LoginForm() {
@@ -45,10 +46,10 @@ export function LoginForm() {
           window.location.href = '/';
         }, 1000);
       } else {
-        toast.error(data.error || 'Login failed. Please try again.');
+        showErrorToast(data.error || 'Login failed. Please try again.', toast);
       }
     } catch (error) {
-      toast.error('An error occurred while logging in. Please try again.');
+      showErrorToast(error, toast);
     } finally {
       setIsLoading(false);
     }

src/components/auth/SignupForm.tsx

@@ -5,6 +5,7 @@ import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '@/components/ui/card';
 import { GitMerge } from 'lucide-react';
 import { toast, Toaster } from 'sonner';
+import { showErrorToast } from '@/lib/utils';
 
 export function SignupForm() {
   const [isLoading, setIsLoading] = useState(false);
@@ -51,10 +52,10 @@ export function SignupForm() {
           window.location.href = '/';
         }, 1500);
       } else {
-        toast.error(data.error || 'Failed to create account. Please try again.');
+        showErrorToast(data.error || 'Failed to create account. Please try again.', toast);
       }
     } catch (error) {
-      toast.error('An error occurred while creating your account. Please try again.');
+      showErrorToast(error, toast);
     } finally {
       setIsLoading(false);
     }

src/components/config/ConfigTabs.tsx

@@ -14,7 +14,7 @@ import type {
 } from '@/types/config';
 import { Button } from '../ui/button';
 import { useAuth } from '@/hooks/useAuth';
-import { apiRequest } from '@/lib/utils';
+import { apiRequest, showErrorToast } from '@/lib/utils';
 import { RefreshCw } from 'lucide-react';
 import { toast } from 'sonner';
 import { Skeleton } from '@/components/ui/skeleton';
@@ -134,16 +134,13 @@ export function ConfigTabs() {
           'Configuration saved successfully! Now import your GitHub data to begin.',
         );
       } else {
-        toast.error(
+        showErrorToast(
           `Failed to save configuration: ${result.message || 'Unknown error'}`,
+          toast
         );
       }
     } catch (error) {
-      toast.error(
-        `An error occurred while saving the configuration: ${
-          error instanceof Error ? error.message : String(error)
-        }`,
-      );
+      showErrorToast(error, toast);
     }
   };
 
@@ -198,18 +195,13 @@ export function ConfigTabs() {
             console.warn('Failed to fetch updated config after auto-save:', fetchError);
           }
         } else {
-          toast.error(
+          showErrorToast(
             `Auto-save failed: ${result.message || 'Unknown error'}`,
-            { duration: 3000 }
+            toast
           );
         }
       } catch (error) {
-        toast.error(
-          `Auto-save error: ${
-            error instanceof Error ? error.message : String(error)
-          }`,
-          { duration: 3000 }
-        );
+        showErrorToast(error, toast);
       } finally {
         setIsAutoSavingSchedule(false);
       }
@@ -266,18 +258,13 @@ export function ConfigTabs() {
             console.warn('Failed to fetch updated config after auto-save:', fetchError);
           }
         } else {
-          toast.error(
+          showErrorToast(
             `Auto-save failed: ${result.message || 'Unknown error'}`,
-            { duration: 3000 }
+            toast
           );
         }
       } catch (error) {
-        toast.error(
-          `Auto-save error: ${
-            error instanceof Error ? error.message : String(error)
-          }`,
-          { duration: 3000 }
-        );
+        showErrorToast(error, toast);
       } finally {
         setIsAutoSavingCleanup(false);
       }

src/components/dashboard/Dashboard.tsx

@@ -5,7 +5,7 @@ import { GitFork, Clock, FlipHorizontal, Building2 } from "lucide-react";
 import { useCallback, useEffect, useRef, useState } from "react";
 import type { MirrorJob, Organization, Repository } from "@/lib/db/schema";
 import { useAuth } from "@/hooks/useAuth";
-import { apiRequest } from "@/lib/utils";
+import { apiRequest, showErrorToast } from "@/lib/utils";
 import type { DashboardApiResponse } from "@/types/dashboard";
 import { useSSE } from "@/hooks/useSEE";
 import { toast } from "sonner";
@@ -103,15 +103,11 @@ export function Dashboard() {
         }
         return true;
       } else {
-        toast.error(response.error || "Error fetching dashboard data");
+        showErrorToast(response.error || "Error fetching dashboard data", toast);
         return false;
       }
     } catch (error) {
-      toast.error(
-        error instanceof Error
-          ? error.message
-          : "Error fetching dashboard data"
-      );
+      showErrorToast(error, toast);
       return false;
     } finally {
       setIsLoading(false);

src/components/organizations/Organization.tsx

@@ -5,7 +5,7 @@ import type { MirrorJob, Organization } from "@/lib/db/schema";
 import { OrganizationList } from "./OrganizationsList";
 import AddOrganizationDialog from "./AddOrganizationDialog";
 import { useAuth } from "@/hooks/useAuth";
-import { apiRequest } from "@/lib/utils";
+import { apiRequest, showErrorToast } from "@/lib/utils";
 import {
   membershipRoleEnum,
   type AddOrganizationApiRequest,
@@ -193,12 +193,10 @@ export function Organization() {
           searchTerm: org,
         }));
       } else {
-        toast.error(response.error || "Error adding organization");
+        showErrorToast(response.error || "Error adding organization", toast);
       }
     } catch (error) {
-      toast.error(
-        error instanceof Error ? error.message : "Error adding organization"
-      );
+      showErrorToast(error, toast);
     } finally {
       setIsLoading(false);
     }
@@ -250,12 +248,10 @@ export function Organization() {
           })
         );
       } else {
-        toast.error(response.error || "Error starting mirror jobs");
+        showErrorToast(response.error || "Error starting mirror jobs", toast);
       }
     } catch (error) {
-      toast.error(
-        error instanceof Error ? error.message : "Error starting mirror jobs"
-      );
+      showErrorToast(error, toast);
     } finally {
       // Reset loading states - we'll let the SSE updates handle status changes
       setLoadingOrgIds(new Set());

src/components/repositories/Repository.tsx

@@ -9,7 +9,7 @@ import {
   type RepositoryApiResponse,
   type RepoStatus,
 } from "@/types/Repository";
-import { apiRequest } from "@/lib/utils";
+import { apiRequest, showErrorToast } from "@/lib/utils";
 import {
   Select,
   SelectContent,
@@ -108,16 +108,14 @@ export default function Repository() {
       } else {
         // Only show error toast for manual refreshes to avoid spam during live updates
         if (!isLiveRefresh) {
-          toast.error(response.error || "Error fetching repositories");
+          showErrorToast(response.error || "Error fetching repositories", toast);
         }
         return false;
       }
     } catch (error) {
       // Only show error toast for manual refreshes to avoid spam during live updates
       if (!isLiveRefresh) {
-        toast.error(
-          error instanceof Error ? error.message : "Error fetching repositories"
-        );
+        showErrorToast(error, toast);
       }
       return false;
     } finally {
@@ -184,12 +182,10 @@ export default function Repository() {
           })
         );
       } else {
-        toast.error(response.error || "Error starting mirror job");
+        showErrorToast(response.error || "Error starting mirror job", toast);
       }
     } catch (error) {
-      toast.error(
-        error instanceof Error ? error.message : "Error starting mirror job"
-      );
+      showErrorToast(error, toast);
     } finally {
       setLoadingRepoIds((prev) => {
         const newSet = new Set(prev);
@@ -248,12 +244,10 @@ export default function Repository() {
           })
         );
       } else {
-        toast.error(response.error || "Error starting mirror jobs");
+        showErrorToast(response.error || "Error starting mirror jobs", toast);
       }
     } catch (error) {
-      toast.error(
-        error instanceof Error ? error.message : "Error starting mirror jobs"
-      );
+      showErrorToast(error, toast);
     } finally {
       // Reset loading states - we'll let the SSE updates handle status changes
       setLoadingRepoIds(new Set());
@@ -287,12 +281,10 @@ export default function Repository() {
           })
         );
       } else {
-        toast.error(response.error || "Error starting sync job");
+        showErrorToast(response.error || "Error starting sync job", toast);
       }
     } catch (error) {
-      toast.error(
-        error instanceof Error ? error.message : "Error starting sync job"
-      );
+      showErrorToast(error, toast);
     } finally {
       setLoadingRepoIds((prev) => {
         const newSet = new Set(prev);
@@ -329,12 +321,10 @@ export default function Repository() {
           })
         );
       } else {
-        toast.error(response.error || "Error retrying job");
+        showErrorToast(response.error || "Error retrying job", toast);
       }
     } catch (error) {
-      toast.error(
-        error instanceof Error ? error.message : "Error retrying job"
-      );
+      showErrorToast(error, toast);
     } finally {
       setLoadingRepoIds((prev) => {
         const newSet = new Set(prev);
@@ -381,12 +371,10 @@ export default function Repository() {
           searchTerm: repo,
         }));
       } else {
-        toast.error(response.error || "Error adding repository");
+        showErrorToast(response.error || "Error adding repository", toast);
       }
     } catch (error) {
-      toast.error(
-        error instanceof Error ? error.message : "Error adding repository"
-      );
+      showErrorToast(error, toast);
     }
   };
 

src/lib/http-client.ts

@@ -70,9 +70,19 @@ export async function httpRequest<T = any>(
         data = await response.json();
       } catch (jsonError) {
         const responseText = await responseClone.text();
-        console.error(`Failed to parse JSON response: ${responseText}`);
+
+        // Enhanced JSON parsing error logging
+        console.error("=== JSON PARSING ERROR ===");
+        console.error("URL:", url);
+        console.error("Status:", response.status, response.statusText);
+        console.error("Content-Type:", contentType);
+        console.error("Response length:", responseText.length);
+        console.error("Response preview (first 500 chars):", responseText.substring(0, 500));
+        console.error("JSON Error:", jsonError instanceof Error ? jsonError.message : String(jsonError));
+        console.error("========================");
+
         throw new HttpError(
-          `Failed to parse JSON response: ${jsonError instanceof Error ? jsonError.message : String(jsonError)}`,
+          `Failed to parse JSON response from ${url}: ${jsonError instanceof Error ? jsonError.message : String(jsonError)}. Response: ${responseText.substring(0, 200)}${responseText.length > 200 ? '...' : ''}`,
           response.status,
           response.statusText,
           responseText

src/lib/utils.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "bun:test";
-import { jsonResponse, formatDate, truncate, safeParse } from "./utils";
+import { jsonResponse, formatDate, truncate, safeParse, parseErrorMessage, showErrorToast } from "./utils";
 
 describe("jsonResponse", () => {
   test("creates a Response with JSON content", () => {
@@ -108,3 +108,53 @@ describe("safeParse", () => {
     expect(parsed).toBe(obj);
   });
 });
+
+describe("parseErrorMessage", () => {
+  test("parses JSON error with error and troubleshooting fields", () => {
+    const errorMessage = JSON.stringify({
+      error: "Unexpected end of JSON input",
+      errorType: "SyntaxError",
+      timestamp: "2025-05-28T09:08:02.37Z",
+      troubleshooting: "JSON parsing error detected. Check Gitea server status and logs. Ensure Gitea is returning valid JSON responses."
+    });
+
+    const result = parseErrorMessage(errorMessage);
+
+    expect(result.title).toBe("Unexpected end of JSON input");
+    expect(result.description).toBe("JSON parsing error detected. Check Gitea server status and logs. Ensure Gitea is returning valid JSON responses.");
+    expect(result.isStructured).toBe(true);
+  });
+
+  test("parses JSON error with title and description fields", () => {
+    const errorMessage = JSON.stringify({
+      title: "Connection Failed",
+      description: "Unable to connect to the server. Please check your network connection."
+    });
+
+    const result = parseErrorMessage(errorMessage);
+
+    expect(result.title).toBe("Connection Failed");
+    expect(result.description).toBe("Unable to connect to the server. Please check your network connection.");
+    expect(result.isStructured).toBe(true);
+  });
+
+  test("handles plain string error messages", () => {
+    const errorMessage = "Simple error message";
+
+    const result = parseErrorMessage(errorMessage);
+
+    expect(result.title).toBe("Simple error message");
+    expect(result.description).toBeUndefined();
+    expect(result.isStructured).toBe(false);
+  });
+
+  test("handles Error objects", () => {
+    const error = new Error("Something went wrong");
+
+    const result = parseErrorMessage(error);
+
+    expect(result.title).toBe("Something went wrong");
+    expect(result.description).toBeUndefined();
+    expect(result.isStructured).toBe(false);
+  });
+});

src/lib/utils.ts

@@ -36,20 +36,141 @@ export function safeParse<T>(value: unknown): T | undefined {
   return value as T;
 }
 
+// Enhanced error message parsing for toast notifications
+export interface ParsedErrorMessage {
+  title: string;
+  description?: string;
+  isStructured: boolean;
+}
+
+export function parseErrorMessage(error: unknown): ParsedErrorMessage {
+  // Handle Error objects
+  if (error instanceof Error) {
+    return parseErrorMessage(error.message);
+  }
+
+  // Handle string messages
+  if (typeof error === "string") {
+    // Try to parse as JSON first
+    try {
+      const parsed = JSON.parse(error);
+
+      // Check for common structured error formats
+      if (typeof parsed === "object" && parsed !== null) {
+        // Format 1: { error: "message", errorType: "type", troubleshooting: "info" }
+        if (parsed.error) {
+          return {
+            title: parsed.error,
+            description: parsed.troubleshooting || parsed.errorType || undefined,
+            isStructured: true,
+          };
+        }
+
+        // Format 2: { title: "title", description: "desc" }
+        if (parsed.title) {
+          return {
+            title: parsed.title,
+            description: parsed.description || undefined,
+            isStructured: true,
+          };
+        }
+
+        // Format 3: { message: "msg", details: "details" }
+        if (parsed.message) {
+          return {
+            title: parsed.message,
+            description: parsed.details || undefined,
+            isStructured: true,
+          };
+        }
+      }
+    } catch {
+      // Not valid JSON, treat as plain string
+    }
+
+    // Plain string message
+    return {
+      title: error,
+      description: undefined,
+      isStructured: false,
+    };
+  }
+
+  // Handle objects directly
+  if (typeof error === "object" && error !== null) {
+    const errorObj = error as any;
+
+    if (errorObj.error) {
+      return {
+        title: errorObj.error,
+        description: errorObj.troubleshooting || errorObj.errorType || undefined,
+        isStructured: true,
+      };
+    }
+
+    if (errorObj.title) {
+      return {
+        title: errorObj.title,
+        description: errorObj.description || undefined,
+        isStructured: true,
+      };
+    }
+
+    if (errorObj.message) {
+      return {
+        title: errorObj.message,
+        description: errorObj.details || undefined,
+        isStructured: true,
+      };
+    }
+  }
+
+  // Fallback for unknown types
+  return {
+    title: String(error),
+    description: undefined,
+    isStructured: false,
+  };
+}
+
+// Enhanced toast helper that parses structured error messages
+export function showErrorToast(error: unknown, toast: any) {
+  const parsed = parseErrorMessage(error);
+
+  if (parsed.description) {
+    // Use sonner's rich toast format with title and description
+    toast.error(parsed.title, {
+      description: parsed.description,
+    });
+  } else {
+    // Simple error toast
+    toast.error(parsed.title);
+  }
+}
+
 // Helper function for API requests
 
 export async function apiRequest<T>(
   endpoint: string,
-  options: RequestInit = {}
+  options: (RequestInit & { data?: any }) = {}
 ): Promise<T> {
   try {
-    const response = await httpRequest<T>(`${API_BASE}${endpoint}`, {
+    // Handle the custom 'data' property by converting it to 'body'
+    const { data, ...requestOptions } = options;
+    const finalOptions: RequestInit = {
       headers: {
         "Content-Type": "application/json",
-        ...(options.headers || {}),
+        ...(requestOptions.headers || {}),
       },
-      ...options,
-    });
+      ...requestOptions,
+    };
+
+    // If data is provided, stringify it and set as body
+    if (data !== undefined) {
+      finalOptions.body = JSON.stringify(data);
+    }
+
+    const response = await httpRequest<T>(`${API_BASE}${endpoint}`, finalOptions);
 
     return response.data;
   } catch (err) {

src/lib/utils/concurrency.test.ts

@@ -67,8 +67,8 @@ describe("processInParallel", () => {
       // Verify that processItem was called for each item
       expect(processItem).toHaveBeenCalledTimes(5);
 
-      // Verify that console.error was called once
-      expect(consoleErrorMock).toHaveBeenCalledTimes(1);
+      // Verify that console.error was called (enhanced logging calls it multiple times)
+      expect(consoleErrorMock).toHaveBeenCalled();
     } finally {
       // Restore console.error
       console.error = originalConsoleError;
@@ -157,8 +157,8 @@ describe("processWithRetry", () => {
       // Verify that onRetry was called twice (for 2 retry attempts)
       expect(onRetry).toHaveBeenCalledTimes(2);
 
-      // Verify that console.error was called once
-      expect(consoleErrorMock).toHaveBeenCalledTimes(1);
+      // Verify that console.error was called (enhanced logging calls it multiple times)
+      expect(consoleErrorMock).toHaveBeenCalled();
     } finally {
       // Restore console.error
       console.error = originalConsoleError;

src/lib/utils/concurrency.ts

@@ -46,11 +46,25 @@ export async function processInParallel<T, R>(
     const batchResults = await Promise.allSettled(batchPromises);
 
     // Process results and handle errors
-    for (const result of batchResults) {
+    for (let j = 0; j < batchResults.length; j++) {
+      const result = batchResults[j];
       if (result.status === 'fulfilled') {
         results.push(result.value);
       } else {
-        console.error('Error processing item:', result.reason);
+        const itemIndex = i + j;
+        console.error("=== BATCH ITEM PROCESSING ERROR ===");
+        console.error("Batch index:", Math.floor(i / concurrencyLimit));
+        console.error("Item index in batch:", j);
+        console.error("Global item index:", itemIndex);
+        console.error("Error type:", result.reason?.constructor?.name);
+        console.error("Error message:", result.reason instanceof Error ? result.reason.message : String(result.reason));
+
+        if (result.reason instanceof Error && result.reason.message.includes('JSON')) {
+          console.error("🚨 JSON parsing error in batch processing");
+          console.error("This indicates an API response issue from Gitea");
+        }
+
+        console.error("==================================");
       }
     }
   }
@@ -139,6 +153,21 @@ export async function processWithRetry<T, R>(
           const delay = retryDelay * Math.pow(2, attempt - 1);
           await new Promise(resolve => setTimeout(resolve, delay));
         } else {
+          // Enhanced error logging for final failure
+          console.error("=== ITEM PROCESSING FAILED (MAX RETRIES EXCEEDED) ===");
+          console.error("Item:", getItemId ? getItemId(item) : 'unknown');
+          console.error("Error type:", lastError.constructor.name);
+          console.error("Error message:", lastError.message);
+          console.error("Attempts made:", maxRetries + 1);
+
+          if (lastError.message.includes('JSON')) {
+            console.error("🚨 JSON-related error detected in item processing");
+            console.error("This suggests an issue with API responses from Gitea");
+          }
+
+          console.error("Stack trace:", lastError.stack);
+          console.error("================================================");
+
           throw lastError;
         }
       }

src/pages/api/job/mirror-repo.ts

@@ -165,11 +165,43 @@ export const POST: APIRoute = async ({ request }) => {
       headers: { "Content-Type": "application/json" },
     });
   } catch (error) {
-    console.error("Error mirroring repositories:", error);
+    // Enhanced error logging for better debugging
+    console.error("=== ERROR MIRRORING REPOSITORIES ===");
+    console.error("Error type:", error?.constructor?.name);
+    console.error("Error message:", error instanceof Error ? error.message : String(error));
+
+    if (error instanceof Error) {
+      console.error("Error stack:", error.stack);
+    }
+
+    // Log additional context
+    console.error("Request details:");
+    console.error("- URL:", request.url);
+    console.error("- Method:", request.method);
+    console.error("- Headers:", Object.fromEntries(request.headers.entries()));
+
+    // If it's a JSON parsing error, provide more context
+    if (error instanceof SyntaxError && error.message.includes('JSON')) {
+      console.error("🚨 JSON PARSING ERROR DETECTED:");
+      console.error("This suggests the response from Gitea API is not valid JSON");
+      console.error("Common causes:");
+      console.error("- Gitea server returned HTML error page instead of JSON");
+      console.error("- Network connection interrupted");
+      console.error("- Gitea server is down or misconfigured");
+      console.error("- Authentication token is invalid");
+      console.error("Check your Gitea server logs and configuration");
+    }
+
+    console.error("=====================================");
+
     return new Response(
       JSON.stringify({
-        error:
-          error instanceof Error ? error.message : "An unknown error occurred",
+        error: error instanceof Error ? error.message : "An unknown error occurred",
+        errorType: error?.constructor?.name || "Unknown",
+        timestamp: new Date().toISOString(),
+        troubleshooting: error instanceof SyntaxError && error.message.includes('JSON')
+          ? "JSON parsing error detected. Check Gitea server status and logs. Ensure Gitea is returning valid JSON responses."
+          : "Check application logs for more details"
       }),
       { status: 500, headers: { "Content-Type": "application/json" } }
     );