web

web / lib/jobs/utils/stuck-detection

lib/jobs/utils/stuck-detection

Shared utility for detecting stuck resources in cleanup jobs.

Functions

isResourceStuck()

isResourceStuck(status, runningStatus, lastRunAt, currentTime, thresholdHours): boolean

Check if a resource is stuck in a “running” state beyond a time threshold.

Important: lastRunAt reflects when the resource was queued (trigger time), not when processing actually started. There can be a significant delay between queueing and execution (e.g., queue backlog, worker restart). Callers should use a generous threshold to avoid falsely resetting jobs that are still actively running. The default threshold in cleanup jobs is 4 hours to account for this gap.

Parameters

status

string | null | undefined

Current status of the resource (e.g., “running”, “completed”)

runningStatus

string

The status value that indicates “running” (e.g., “running”)

lastRunAt

string | Date | null | undefined

When the resource was queued/triggered (ISO string or Date)

currentTime

Date

Current time for comparison

thresholdHours

number

How many hours before considering it stuck

Returns

boolean

hasActivePayloadJob()

hasActivePayloadJob(payload, resourceFieldPath, resourceId): Promise<boolean>

Check if a Payload job is actively running for the given resource.

Queries the payload-jobs collection for jobs whose input references the resource and whose processing status indicates they are currently being worked on. This provides a secondary safety check before resetting a “stuck” resource.

Parameters

payload

BasePayload

Payload instance

resourceFieldPath

string

The dot-path in job input that references the resource (e.g., “input.scheduledIngestId”)

resourceId

string | number

The resource ID to match

Returns

Promise<boolean>

true if an active Payload job exists for this resource