Task Triggering Services provide the entry point for executing tasks in the Trigger.dev platform. These services handle incoming trigger requests from the Management API, perform validation, manage idempotency, process payloads, select appropriate queues, and ultimately create task runs in the execution engine. This document covers the service layer architecture, version-aware routing (V1 vs V2 engines), and the validation/processing pipeline that prepares triggers for execution.
For information about the actual execution lifecycle after triggering, see Run Lifecycle and State Machine. For queue management and dequeuing logic, see Queue Management. For batch triggering, see Batch Processing.
The task triggering system uses a version-aware architecture that routes requests to either the legacy V1 engine or the current V2 RunEngine based on environment configuration and worker version compatibility.
Service Layer Flow: Trigger requests enter through TriggerTaskService, which determines the engine version and routes to either V1 or V2 processing paths. V2 uses a modular concern-based architecture where validation, queue management, payload processing, and idempotency checks are separated into reusable components.
Sources:
The system supports two engine versions with automatic routing based on environment configuration and worker compatibility.
The TriggerTaskService class serves as the unified entry point for all trigger requests:
Engine Version Detection: The determineEngineVersion() function considers the environment's engine version setting, worker version locks, and optional override parameters to select V1 or V2.
Sources:
| Aspect | V1 (Legacy) | V2 (RunEngine) |
|---|---|---|
| Architecture | Monolithic service | Modular concerns |
| Validation | Inline | DefaultTriggerTaskValidator |
| Queue Management | Simple selection | DefaultQueueManager with limits |
| Payload Handling | Basic | DefaultPayloadProcessor with offloading |
| Idempotency | Database-level | IdempotencyKeyConcern with caching |
| Tracing | Basic | DefaultTraceEventsConcern integration |
| Debouncing | Not supported | Full DebounceSystem support |
| Execution Engine | Legacy task runner | RunEngine with state machine |
The V2 triggering path uses a modular pipeline where each concern handles a specific responsibility.
Pipeline Flow: Each concern processes the request in sequence, with the idempotency check potentially short-circuiting the flow if a duplicate key is detected.
Sources:
The DefaultTriggerTaskValidator performs comprehensive validation before allowing a task to be triggered.
Validation Rules:
MAX_ATTEMPTS constant)parentTaskRunId is specified, parent must exist and not be in a final stateSources:
The OutOfEntitlementError is a special error type that indicates the organization has run out of credits:
Sources:
The IdempotencyKeyConcern prevents duplicate task executions by deduplicating requests with the same idempotency key.
Idempotency Scopes: The system supports three scopes defined in idempotencyKeyOptions:
run: Key is unique per run (default)attempt: Key is unique per attempt (allows retries with same key)global: Key is globally unique across all environmentsDatabase Constraint: Idempotency is enforced by a unique constraint on (runtimeEnvironmentId, idempotencyKey) in the TaskRun table. Duplicate inserts will trigger a Prisma error with code P2002.
Sources:
The DefaultPayloadProcessor handles payload size validation and automatic offloading to object storage for large payloads.
Payload Thresholds (configured in apps/webapp/app/env.server.ts543-546):
Offloading Strategy: When a payload exceeds the threshold:
payloadType="application/store"Sources:
The DefaultQueueManager selects the appropriate queue and enforces queue size limits.
Queue Naming Convention:
task/{taskIdentifier} - e.g., task/send-emailhigh-prioritybatch-processingQueue Size Limits (configured in apps/webapp/app/env.server.ts549-550):
Sources:
The RunEngine.trigger() method is the core V2 implementation that creates and enqueues task runs.
The TriggerParams type defines all parameters accepted by RunEngine.trigger():
| Parameter | Type | Purpose |
|---|---|---|
friendlyId | string | Human-readable run ID (e.g., run_abc123) |
environment | MinimalAuthenticatedEnvironment | Environment context (org, project, env) |
taskIdentifier | string | Task identifier (e.g., send-email) |
payload / payloadType | string | Serialized payload and content type |
idempotencyKey | string? | Deduplication key |
delayUntil | Date? | Delayed execution timestamp |
ttl | string? | Time-to-live (e.g., 7d) |
maxAttempts | number? | Maximum retry attempts (1-25) |
maxDurationInSeconds | number? | Execution timeout |
tags | Array | Run tags for filtering |
parentTaskRunId | string? | Parent run for triggerAndWait |
resumeParentOnCompletion | boolean? | Whether to resume parent after completion |
batch | object? | Batch context (id, index) |
debounce | object? | Debounce configuration |
machine | MachinePresetName? | Machine preset override |
metadata / metadataType | string? | Serialized metadata |
traceContext / traceId / spanId | OpenTelemetry | Trace correlation |
Sources:
Key Steps:
defaultMaxTtl if neededTaskRun record with initial ExecutionSnapshottriggerAndWait, block parent on child's waitpointdelayUntil, schedule future enqueuingSources:
The debounce system allows trailing-edge debouncing where repeated triggers within a time window update an existing delayed run:
Debounce Modes:
Max Duration: Enforced by RUN_ENGINE_MAXIMUM_DEBOUNCE_DURATION_MS (default 1 hour). Prevents indefinite debouncing.
Sources:
The TaskRun database record is created with comprehensive metadata.
| Field | Description | Set During Trigger |
|---|---|---|
id | Internal UUID generated from friendlyId | ✓ |
friendlyId | Human-readable ID (e.g., run_abc123) | ✓ |
status | Run status (DELAYED or PENDING) | ✓ |
engine | Engine version (V2) | ✓ |
runtimeEnvironmentId | Environment ID | ✓ |
organizationId | Organization ID | ✓ |
projectId | Project ID | ✓ |
taskIdentifier | Task identifier | ✓ |
payload / payloadType | Task payload (inline or S3 reference) | ✓ |
context | Execution context | ✓ |
traceContext / traceId / spanId | OpenTelemetry trace | ✓ |
idempotencyKey / idempotencyKeyExpiresAt | Deduplication | ✓ |
queue / lockedQueueId | Queue assignment | ✓ |
delayUntil | Delayed execution time | ✓ (if delayed) |
ttl | Time-to-live | ✓ (if set) |
maxAttempts | Maximum retry attempts | ✓ (if set) |
maxDurationInSeconds | Execution timeout | ✓ (if set) |
machinePreset | Machine configuration | ✓ (if set) |
tags / runTags | Run tags | ✓ |
parentTaskRunId / rootTaskRunId | Task tree | ✓ (if child) |
batchId | Batch context | ✓ (if batch) |
metadata / metadataType | Metadata | ✓ (if set) |
debounce | Debounce config | ✓ (if debounced) |
lockedById | Background worker task ID | Set during dequeue |
lockedToVersionId | Worker version | Set during dequeue |
attemptNumber | Current attempt | Set during attempt creation |
usageDurationMs / costInCents | Billing | Set during completion |
Concurrent Creation: The executionSnapshots.create nested creation ensures the initial snapshot is atomically created with the run.
Sources:
Every run starts with an initial ExecutionSnapshot:
Snapshot Purpose: The snapshot system provides an immutable audit trail of execution state changes. For details, see Execution Snapshots.
Sources:
The triggerAndWait() pattern allows tasks to trigger child tasks and wait for their completion.
Waitpoint Types:
Parent Blocking: When resumeParentOnCompletion=true, a TaskRunWaitpoint record is created linking the parent to the child's waitpoint. The parent cannot continue until the waitpoint is completed.
Sources:
Task triggering can fail at various stages with specific error types.
Error Recovery:
isCached=truePrisma Error Codes:
P2002: Unique constraint violation (duplicate idempotency key)Sources:
Environment variables controlling task triggering behavior.
| Variable | Default | Description |
|---|---|---|
DEFAULT_DEV_ENV_EXECUTION_ATTEMPTS | 1 | Default max attempts for dev environments |
DEFAULT_ENV_EXECUTION_CONCURRENCY_LIMIT | 100 | Default concurrent runs per environment |
DEFAULT_ORG_EXECUTION_CONCURRENCY_LIMIT | 300 | Default concurrent runs per organization |
Sources:
| Variable | Default | Description |
|---|---|---|
TASK_PAYLOAD_OFFLOAD_THRESHOLD | 524,288 (512KB) | Size threshold for S3 offloading |
TASK_PAYLOAD_MAXIMUM_SIZE | 3,145,728 (3MB) | Maximum payload size |
BATCH_TASK_PAYLOAD_MAXIMUM_SIZE | 1,000,000 (1MB) | Maximum batch item payload |
TASK_RUN_METADATA_MAXIMUM_SIZE | 262,144 (256KB) | Maximum metadata size |
Sources:
| Variable | Default | Description |
|---|---|---|
MAXIMUM_DEV_QUEUE_SIZE | undefined | Max queue size for dev environments |
MAXIMUM_DEPLOYED_QUEUE_SIZE | undefined | Max queue size for deployed environments |
QUEUE_SIZE_CACHE_TTL_MS | 1,000 | Queue size cache TTL |
QUEUE_SIZE_CACHE_MAX_SIZE | 5,000 | Queue size cache max entries |
Sources:
| Variable | Default | Description |
|---|---|---|
RUN_ENGINE_MAXIMUM_DEBOUNCE_DURATION_MS | 3,600,000 (1h) | Maximum debounce duration |
Sources:
| Variable | Default | Description |
|---|---|---|
RUN_ENGINE_DEFAULT_MAX_TTL | undefined | Default maximum TTL for all runs (e.g., "14d") |
Sources:
The service layer returns structured results indicating success or cached responses.
Fields:
run: The created or cached TaskRun recordisCached: true if returned from idempotency cache, false if newly createdUsage: Clients can use isCached to determine whether the trigger was a duplicate request.
Sources:
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.