From ccd8ef35c35bad5de6fd7e0e9950148f3f81f9a9 Mon Sep 17 00:00:00 2001
From: Bas van den Aakster <bvdaakster@gmail.com>
Date: Sun, 14 Sep 2025 18:00:23 +0200
Subject: [PATCH] Fix error handling and improve error messages

- Fix inconsistent error handling in sendEmailTask by re-throwing original Error instances
- Preserve stack traces and error context instead of creating new Error wrappers
- Improve generic error messages in emailProcessor utilities with specific details
- Add actionable guidance for common configuration issues
- Help developers understand what went wrong and how to fix it
- Bump version to 0.4.1
---
 package.json                |  2 +-
 src/jobs/sendEmailTask.ts   |  4 +++-
 src/utils/emailProcessor.ts | 30 ++++++++++++++++++++++++++----
 3 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/package.json b/package.json
index 1448d52..85bef84 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@xtr-dev/payload-mailing",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Template-based email system with scheduling and job processing for PayloadCMS",
   "type": "module",
   "main": "dist/index.js",
diff --git a/src/jobs/sendEmailTask.ts b/src/jobs/sendEmailTask.ts
index 170bbca..12755d3 100644
--- a/src/jobs/sendEmailTask.ts
+++ b/src/jobs/sendEmailTask.ts
@@ -242,9 +242,11 @@ export const sendEmailJob = {
       }
 
     } catch (error) {
+      // Re-throw Error instances to preserve stack trace and error context
       if (error instanceof Error) {
-        throw new Error(`Failed to process email: ${error.message}`, { cause: error })
+        throw error
       } else {
+        // Only wrap non-Error values
         throw new Error(`Failed to process email: ${String(error)}`)
       }
     }
diff --git a/src/utils/emailProcessor.ts b/src/utils/emailProcessor.ts
index b69c1da..ff7daf7 100644
--- a/src/utils/emailProcessor.ts
+++ b/src/utils/emailProcessor.ts
@@ -10,8 +10,19 @@ export async function processEmailById(payload: Payload, emailId: string): Promi
   // Get mailing context from payload
   const mailingContext = (payload as any).mailing
 
-  if (!mailingContext || !mailingContext.service) {
-    throw new Error('Mailing plugin not properly initialized')
+  if (!mailingContext) {
+    throw new Error(
+      'Mailing plugin not found on payload instance. ' +
+      'Ensure the mailingPlugin is properly configured in your Payload config plugins array.'
+    )
+  }
+
+  if (!mailingContext.service) {
+    throw new Error(
+      'Mailing service not available. ' +
+      'The plugin may not have completed initialization. ' +
+      'Check that email configuration is properly set up in your Payload config.'
+    )
   }
 
   // Process the specific email
@@ -27,8 +38,19 @@ export async function processAllEmails(payload: Payload): Promise<void> {
   // Get mailing context from payload
   const mailingContext = (payload as any).mailing
 
-  if (!mailingContext || !mailingContext.service) {
-    throw new Error('Mailing plugin not properly initialized')
+  if (!mailingContext) {
+    throw new Error(
+      'Mailing plugin not found on payload instance. ' +
+      'Ensure the mailingPlugin is properly configured in your Payload config plugins array.'
+    )
+  }
+
+  if (!mailingContext.service) {
+    throw new Error(
+      'Mailing service not available. ' +
+      'The plugin may not have completed initialization. ' +
+      'Check that email configuration is properly set up in your Payload config.'
+    )
   }
 
   // Process pending emails first