commit

Author: AlessioGr

packages/payload/src/queues/errors/handleWorkflowError.ts

@@ -44,10 +44,16 @@ export async function handleWorkflowError({
     stack: error.stack,
   }
 
-  const { hasFinalError, maxWorkflowRetries, waitUntil } = getWorkflowRetryBehavior({
-    job,
-    retriesConfig: workflowConfig.retries!,
-  })
+  // No retries configured => permanently fail.
+  const hasNoRetriesConfigured =
+    workflowConfig.retries === undefined || workflowConfig.retries === null
+
+  const { hasFinalError, maxWorkflowRetries, waitUntil } = hasNoRetriesConfigured
+    ? { hasFinalError: true as const, maxWorkflowRetries: undefined, waitUntil: undefined }
+    : getWorkflowRetryBehavior({
+        job,
+        retriesConfig: workflowConfig.retries,
+      })
 
   if (!hasFinalError) {
     if (job.waitUntil) {

packages/payload/src/queues/operations/runJobs/index.ts

@@ -349,7 +349,8 @@ export const runJobs = async (args: RunJobsArgs): Promise<RunJobsResult> => {
     }
 
     if (!workflowConfig) {
-      // Permanently fail jobs that reference a workflow or task that is no longer registered in config, as they can never be completed successfully. No point in retrying them
+      // Permanently fail jobs whose task/workflow slug is no longer registered in config — they can never complete.
+      const errorMessage = `${job.taskSlug ? `Task '${job.taskSlug}'` : `Workflow '${job.workflowSlug}'`} is not registered in payload.config.jobs.`
 
       if (!silent || (typeof silent === 'object' && !silent.error)) {
         payload.logger.error({

test/queues/getConfig.ts

@@ -38,6 +38,8 @@ import { selfCancelWorkflow } from './workflows/selfCancel.js'
 import { subTaskWorkflow } from './workflows/subTask.js'
 import { subTaskFailsWorkflow } from './workflows/subTaskFails.js'
 import { supersedesConcurrencyWorkflow } from './workflows/supersedesConcurrency.js'
+import { throwsInHandlerNoRetriesWorkflow } from './workflows/throwsInHandlerNoRetries.js'
+import { throwsInHandlerRetries1Workflow } from './workflows/throwsInHandlerRetries1.js'
 import { updatePostWorkflow } from './workflows/updatePost.js'
 import { updatePostJSONWorkflow } from './workflows/updatePostJSON.js'
 import { workflowAndTasksRetriesUndefinedWorkflow } from './workflows/workflowAndTasksRetriesUndefined.js'
@@ -179,6 +181,8 @@ export const getConfig: () => Partial<Config> = () => ({
       noConcurrencyWorkflow,
       queueSpecificConcurrencyWorkflow,
       supersedesConcurrencyWorkflow,
+      throwsInHandlerNoRetriesWorkflow,
+      throwsInHandlerRetries1Workflow,
     ],
   },
   editor: lexicalEditor(),

test/queues/int.spec.ts

@@ -973,6 +973,78 @@ describe('Queues - Payload', () => {
       expect(jobAfterRun.processing).toBe(false)
       expect(jobAfterRun.totalTried).toBe(1)
     })
+
+    it('should permanently fail when a workflow handler calls a task that has been removed', async () => {
+      payload.config.jobs.deleteJobOnComplete = false
+
+      const job = await payload.jobs.queue({
+        workflow: 'workflowNoRetriesSet',
+        input: {
+          message: 'queued before referenced task removal',
+        },
+      })
+
+      payload.config.jobs.tasks = originalTasks!.filter((t) => t.slug !== 'CreateSimple')
+
+      await payload.jobs.run({ silent: true })
+
+      const jobAfterRun = await payload.findByID({
+        collection: 'payload-jobs',
+        id: job.id,
+      })
+
+      expect(jobAfterRun.hasError).toBe(true)
+      expect(jobAfterRun.processing).toBe(false)
+      expect(jobAfterRun.totalTried).toBe(1)
+    })
+  })
+
+  it('should not retry a workflow with no retries configured when its handler throws', async () => {
+    payload.config.jobs.deleteJobOnComplete = false
+
+    const job = await payload.jobs.queue({
+      workflow: 'throwsInHandlerNoRetries',
+      input: {},
+    })
+
+    await payload.jobs.run({ silent: true })
+
+    const jobAfterRun = await payload.findByID({
+      collection: 'payload-jobs',
+      id: job.id,
+    })
+
+    expect(jobAfterRun.hasError).toBe(true)
+    expect(jobAfterRun.processing).toBe(false)
+    expect(jobAfterRun.totalTried).toBe(1)
+  })
+
+  it('should retry a workflow with retries=1 exactly once when its handler throws', async () => {
+    payload.config.jobs.deleteJobOnComplete = false
+
+    const job = await payload.jobs.queue({
+      workflow: 'throwsInHandlerRetries1',
+      input: {},
+    })
+
+    let hasJobsRemaining = true
+    while (hasJobsRemaining) {
+      const response = await payload.jobs.run({ silent: true })
+      if (response.noJobsRemaining) {
+        hasJobsRemaining = false
+      }
+    }
+
+    const jobAfterRun = await payload.findByID({
+      collection: 'payload-jobs',
+      id: job.id,
+    })
+
+    // Initial attempt + 1 retry = 2. Once hasError is true the queue stops picking it up,
+    // so the loop naturally bounds at exactly 2 attempts.
+    expect(jobAfterRun.totalTried).toBe(2)
+    expect(jobAfterRun.hasError).toBe(true)
+    expect(jobAfterRun.processing).toBe(false)
   })
 
   it('can queue and run via the endpoint single tasks without workflows', async () => {

test/queues/payload-types.ts

@@ -94,6 +94,9 @@ export interface Config {
   globals: {};
   globalsSelect: {};
   locale: null;
+  widgets: {
+    collections: CollectionsWidget;
+  };
   user: User;
   jobs: {
     tasks: {
@@ -140,6 +143,8 @@ export interface Config {
       noConcurrency: WorkflowNoConcurrency;
       queueSpecificConcurrency: WorkflowQueueSpecificConcurrency;
       supersedesConcurrency: WorkflowSupersedesConcurrency;
+      throwsInHandlerNoRetries: WorkflowThrowsInHandlerNoRetries;
+      throwsInHandlerRetries1: WorkflowThrowsInHandlerRetries1;
     };
   };
 }
@@ -365,6 +370,8 @@ export interface PayloadJob {
         | 'noConcurrency'
         | 'queueSpecificConcurrency'
         | 'supersedesConcurrency'
+        | 'throwsInHandlerNoRetries'
+        | 'throwsInHandlerRetries1'
       )
     | null;
   taskSlug?:
@@ -571,6 +578,16 @@ export interface PayloadMigrationsSelect<T extends boolean = true> {
   updatedAt?: T;
   createdAt?: T;
 }
+/**
+ * This interface was referenced by `Config`'s JSON-Schema
+ * via the `definition` "collections_widget".
+ */
+export interface CollectionsWidget {
+  data?: {
+    [k: string]: unknown;
+  };
+  width: 'full';
+}
 /**
  * This interface was referenced by `Config`'s JSON-Schema
  * via the `definition` "MyUpdatePostType".
@@ -932,6 +949,20 @@ export interface WorkflowSupersedesConcurrency {
     delayMs?: number | null;
   };
 }
+/**
+ * This interface was referenced by `Config`'s JSON-Schema
+ * via the `definition` "WorkflowThrowsInHandlerNoRetries".
+ */
+export interface WorkflowThrowsInHandlerNoRetries {
+  input?: unknown;
+}
+/**
+ * This interface was referenced by `Config`'s JSON-Schema
+ * via the `definition` "WorkflowThrowsInHandlerRetries1".
+ */
+export interface WorkflowThrowsInHandlerRetries1 {
+  input?: unknown;
+}
 /**
  * This interface was referenced by `Config`'s JSON-Schema
  * via the `definition` "auth".

test/queues/workflows/throwsInHandlerNoRetries.ts

@@ -0,0 +1,10 @@
+import type { WorkflowConfig } from 'payload'
+
+export const throwsInHandlerNoRetriesWorkflow: WorkflowConfig<'throwsInHandlerNoRetries'> = {
+  slug: 'throwsInHandlerNoRetries',
+  inputSchema: [],
+  // Intentionally no `retries` set — exercises the default no-retries-on-workflow-error behavior
+  handler: () => {
+    throw new Error('This workflow throws in its handler')
+  },
+}

test/queues/workflows/throwsInHandlerRetries1.ts

@@ -0,0 +1,10 @@
+import type { WorkflowConfig } from 'payload'
+
+export const throwsInHandlerRetries1Workflow: WorkflowConfig<'throwsInHandlerRetries1'> = {
+  slug: 'throwsInHandlerRetries1',
+  inputSchema: [],
+  retries: 1,
+  handler: () => {
+    throw new Error('This workflow throws in its handler')
+  },
+}