Worker Execution

Relevant source files

• apps/webapp/app/models/runtimeEnvironment.server.ts
• apps/webapp/app/services/logger.server.ts
• apps/webapp/app/services/worker.server.ts
• apps/webapp/app/utils/taskListToTree.ts
• apps/webapp/app/v3/services/triggerTask.server.ts
• packages/core/src/logger.ts

Worker execution in the Trigger.dev platform refers to the background job processing system that handles asynchronous platform operations. This page documents the ZodWorker system, the workerCatalog that defines available background jobs, the handler functions that process these jobs, and the migration from a monolithic worker file to specialized worker modules.

This system is distinct from task execution workers (which run user-defined task code). Background workers handle internal platform operations like sending emails, processing alerts, retrying failed attempts, and managing deployments.

For information about task execution in user code, see sections on the Run Engine. For information about queue management, see Queue Management.

Background Worker System Architecture

Sources: apps/webapp/app/services/worker.server.ts1-346

The background worker system uses ZodWorker, a wrapper around Graphile Worker that provides type-safe job definitions with Zod schemas. Jobs are enqueued from service classes throughout the application and processed asynchronously by worker handlers.

ZodWorker Class

ZodWorker is a type-safe wrapper around Graphile Worker that provides schema validation, job registration, and execution management. It is defined in the internal packages and used by the webapp to process background jobs.

ZodWorker Initialization

Sources: apps/webapp/app/services/worker.server.ts133-148

Configuration Options:

• name: Identifier for the worker instance
• prisma / replica: Database clients for job persistence
• runnerOptions: Graphile Worker configuration (connection, concurrency, polling)
• logger: Structured logging instance
• shutdownTimeoutInMs: Grace period for completing jobs on shutdown
• schema: workerCatalog defining job payload schemas
• recurringTasks: Cron-style scheduled jobs
• tasks: Handler functions for each job type

Worker Instance Management

Sources: apps/webapp/app/services/worker.server.ts105-122

In development, the worker is cached in a global variable to prevent recreation on hot reload. In production, a new instance is created at startup.

Worker Initialization

Sources: apps/webapp/app/services/worker.server.ts124-131

The init() function runs Graphile Worker schema migrations and starts the worker if WORKER_ENABLED is set. This allows running the webapp with workers disabled.

Worker Catalog

The workerCatalog defines all available background job types with Zod schemas for type-safe payload validation. It maps job identifiers to their payload schemas.

Catalog Structure

Sources: apps/webapp/app/services/worker.server.ts33-103

Key Characteristics:

• Each job has a string identifier (e.g., "v3.retryAttempt")
• Payload schema defined using Zod for runtime validation
• Many jobs marked as @deprecated with migration notes
• Clear separation between legacy and new implementations

Job Naming Conventions

Job identifiers follow patterns:

• scheduleEmail: Legacy email delivery
• v3.*: Version 3 platform operations
• runengine.*: Run engine specific operations
• Descriptive names like performTaskRunAlerts, enqueueDelayedRun

Sources: apps/webapp/app/services/worker.server.ts33-103

Background Job Handlers

Job handlers are registered in the tasks configuration of ZodWorker. Each handler specifies priority, retry attempts, and the execution function.

Handler Configuration Structure

Sources: apps/webapp/app/services/worker.server.ts158-176

Handler Properties:

• priority: Integer for job ordering (lower = higher priority)
• maxAttempts: Number of retry attempts before permanent failure
• handler: Async function receiving validated payload and job metadata

Common Handler Patterns

Sources: apps/webapp/app/services/worker.server.ts158-342

Most handlers follow the pattern:

1. Receive validated payload
2. Instantiate appropriate service class
3. Call service method with payload parameters
4. Service performs database operations or external API calls
5. Return result or throw error for retry

Example Handlers

Email Delivery:

Retry Attempt:

Batch Processing:

Sources: apps/webapp/app/services/worker.server.ts160-166 apps/webapp/app/services/worker.server.ts273-281 apps/webapp/app/services/worker.server.ts323-331

Handler Execution Context

Sources: apps/webapp/app/services/worker.server.ts158-342

Handlers receive:

• Payload: Validated against Zod schema from workerCatalog
• Job Object: Contains attempts, max_attempts, job ID, and other metadata
• Helpers: Optional helpers for advanced job control

The handler can:

• Return successfully to mark job complete
• Throw error to trigger retry (up to maxAttempts)
• Access attempt number via job.attempts

Recurring Tasks

ZodWorker supports recurring tasks that run on cron-style schedules for periodic maintenance operations.

Concurrency Monitor

Sources: apps/webapp/app/services/worker.server.ts149-157

The concurrency monitor runs every 5 minutes to check and manage queue concurrency limits. It uses the MarqsConcurrencyMonitor service to monitor V3 queues.

Recurring Task Configuration:

• match: Cron expression for scheduling (format: minute hour day month dayOfWeek)
• handler: Function that executes on schedule
• helpers: Provides abortSignal for graceful cancellation

This pattern allows background maintenance tasks to run automatically without manual triggering.

Sources: apps/webapp/app/services/worker.server.ts149-157

Migration to Specialized Workers

The codebase is undergoing a migration from a monolithic worker.server.ts to specialized worker files. This improves code organization and allows independent scaling of worker types.

Migration Architecture

Sources: apps/webapp/app/services/worker.server.ts34-103

Deprecation Markers

Throughout worker.server.ts, jobs are marked with deprecation comments indicating their new location:

Sources: apps/webapp/app/services/worker.server.ts34-77

Migration Categories

Job Category	Destination	Purpose
Email delivery	commonWorker.server.ts	Common platform operations
Alert operations	alertsWorker.server.ts	Alert delivery and processing
Scheduled task triggers	ScheduleEngine	Cron-based task triggering
Legacy run operations	legacyRunEngineWorker.server.ts	V1 run engine operations
Task dependencies	commonWorker.server.ts	Dependency resolution
Batch processing	commonWorker.server.ts	Batch task operations
Deployment operations	commonWorker.server.ts	Deployment lifecycle

Sources: apps/webapp/app/services/worker.server.ts34-103

Still-Active Jobs

Some jobs remain in worker.server.ts:

Bulk Actions:

Batch Run Resume (used in transactions):

Batch Processing:

Sources: apps/webapp/app/services/worker.server.ts37-39 apps/webapp/app/services/worker.server.ts71-76 apps/webapp/app/services/worker.server.ts100-103

Benefits of Specialization

Code Organization:

• Related jobs grouped together
• Clearer responsibilities per worker file
• Easier to understand job purposes

Operational Benefits:

• Independent scaling of worker types
• Different concurrency settings per worker category
• Targeted monitoring and alerting

Development Benefits:

• Reduced merge conflicts
• Faster iteration on specific job types
• Easier testing of job categories

Job Execution Flow

Complete Job Processing Sequence

Sources: apps/webapp/app/services/worker.server.ts133-343

Job Lifecycle States

Sources: apps/webapp/app/services/worker.server.ts158-342

Jobs progress through states managed by Graphile Worker:

1. Pending: Job enqueued, waiting for worker
2. Running: Worker processing job handler
3. Retry: Error thrown, attempts < maxAttempts
4. Completed: Handler returned successfully
5. Failed: Max attempts reached, moved to failures table

Job Priority and Ordering

Sources: apps/webapp/app/services/worker.server.ts273-291

Priority System:

• Lower numbers = higher priority
• Jobs with priority 0 processed before higher numbers
• Used to prioritize critical operations

Retry Configuration:

• maxAttempts varies by job criticality
• Email delivery: 3 attempts
• Deployment operations: 5 attempts
• Critical background tasks: 8 attempts

Summary

Worker execution in Trigger.dev involves multiple coordinated layers:

1. TaskExecutor: Core execution engine handling lifecycle hooks, error handling, and task code execution
2. Worker Processes: Separate entry points for dev (dev-run-worker.ts) and production (managed-run-worker.ts) with different resource tracking
3. TaskRunProcess: Process wrapper managing child process lifecycle, IPC communication, and error recovery
4. Process Pool: Optional reuse mechanism in dev mode to improve performance
5. Communication: Type-safe IPC messaging between coordinator and workers

The architecture provides isolation, observability, and flexibility while supporting both rapid development iteration and production reliability.

Sources: packages/core/src/v3/workers/taskExecutor.ts66-1370 packages/cli-v3/src/entryPoints/dev-run-worker.ts1-735 packages/cli-v3/src/entryPoints/managed-run-worker.ts1-559 packages/cli-v3/src/executions/taskRunProcess.ts64-518 packages/cli-v3/src/dev/taskRunProcessPool.ts20-349