Error reference
Typed producer, worker, waiting, storage, and Redis failures.
EffectMQ exposes predictable failures in Effect error channels. Handler-domain failures are distinct from infrastructure and protocol failures.
Task definition and identity
| Tag | Fields | Meaning |
|---|---|---|
TaskIdentityGenerationError | taskName, cause | The idempotency callback or Crypto UUID generation failed. |
Invalid task retry, storage, retention, and scheduler backfill configuration is a programmer defect detected by the first consuming operation. Definition invariants do not appear in typed error unions.
Offering
| Tag | Fields | Meaning |
|---|---|---|
TaskOptionsError | field, constraint, actual | An offer delay, retry cap, or stalled-attempt cap is invalid. |
IndeterminateWriteError | queue, taskId, cause | Redis may have committed the offer before the connection failed. |
RetentionContextRequired | queue, taskId | Current-task result retention was requested outside a managed handler. |
OfferError also includes storage, engine, and Schema errors.
Completion and leases
| Tag | Fields | Meaning |
|---|---|---|
LeaseLost | prefix, taskId, cause | The attempt no longer owns the generation. |
TaskEngineError | reason, cause | Redis transport, script, reply, relationship, commit, or lease boundary failure. |
RetryPolicyError | queue, taskId, cause | Retry-policy evaluation failed or retained failure history cannot replay it safely. |
TaskEngineError.reason._tag is one of InvalidInput, TransportFailure, ScriptFailure,
InvalidReply, RelationshipLimit, IndeterminateCommit, or LeaseLost.
Waiting
| Tag | Fields | Meaning |
|---|---|---|
TaskHandleMismatch | expectedQueue, actualQueue, expectedTaskName, actualTaskName | The handle does not match the queue or task descriptor. |
InvalidCursor | cursor | The event cursor is not a valid Redis stream id. |
TaskFailed | handle, failure | The exact generation settled with the typed handler or built-in failure. |
TaskNotFound | handle | No task record, result, or known generation exists. |
ResultExpired | handle, latestGeneration | The handle's retained result is unavailable. |
CallerTimeout | handle, timeout | The caller-local deadline elapsed; task execution continues. |
CursorExpired | requested, earliest | Event retention trimmed the requested position. |
Built-in terminal task failures are tagged ~effectmq/Error/Stalled and
~effectmq/Error/Canceled.
Task progress and history
These errors are exported by TaskHistory (including the stable
@effectmq/core/TaskHistory subpath):
| Tag | Fields | Meaning |
|---|---|---|
HistoryDisabled | queue, taskId, generation | The definition or stored generation has no enabled history. |
HistoryUnavailable | queue, taskId, generation | This generation's task record is no longer available. |
InvalidHistoryCursor | reason, optional cursor | The cursor is malformed, belongs to another history, or the page size is invalid. |
HistoryCursorExpired | requested, earliestCursor | Entries after the requested position were trimmed. |
CorruptHistory | cause | Stored history has an invalid structure. |
ProgressWriteError | queue, taskId, generation, reason, cause | Progress encoding or persistence failed; reason is WriteFailed or IndeterminateWrite. |
An uncaught ProgressWriteError leaves the attempt unsettled for lease recovery;
it is not encoded as a handler-domain failure. An indeterminate append may
already be stored and is not automatically replayed. History reads also expose
handle, schema, storage, and engine failures. See
reporting progress for gap recovery and
retention behavior.
Application event queues
EventEngine.EventEngineError carries code, message, and optional cause,
operation, and eventId. Its codes are InvalidInput, ConfigurationConflict,
CapacityExceeded, SubscriptionMissing, LeaseLost, EventNotActive,
CorruptStorage, IndeterminateWrite, and IdentityError.
For IndeterminateWrite, inspect the supplied event identity before deciding
whether to emit again: emissions are not deduplicated. Stale delivery ownership
uses the LeaseLost code. processOne also propagates typed handler failures
after releasing the delivery for retry. See the
EventQueue reference.
Storage protocol
| Tag | Meaning |
|---|---|
UnsupportedStorageValue | The value includes an unsupported type, unsafe number, class instance, or cycle. |
StorageLimitExceeded | Encoded payload, success, failure, or progress exceeds maxValueBytes. |
StorageCountLimitExceeded | A task-retention relationship collection reached its limit. |
CorruptStorageValue | Stored data has an invalid envelope or semantic shape. |
StorageEncodingError | MessagePack or base64 encoding failed. |
StorageDecodingError | Byte, base64, or MessagePack decoding failed. |
UnsupportedProtocolVersion | The envelope version is not readable by this release. |
SchemaIdentityMismatch | The stored value or handle belongs to another schema identity. |
Live configuration
| Tag | Meaning |
|---|---|
WorkerConfigurationError | Invalid worker concurrency, timing, or processing options; includes field, constraint, and actual. |
ProcessingConfigurationError | Invalid lease or heartbeat options passed directly to queue processing; includes field, constraint, and actual. |
TaskEngineConfigurationError | maintenanceBatchSize is outside 1–1,000. |
InvalidRedisConfiguration | Standalone pool bounds or timeouts are invalid. |
UnsupportedRedisTopology | Redis Cluster was configured or detected. |
Recovery matrix
| Failure | Recovery |
|---|---|
TaskOptionsError | Correct the reported numeric option before retrying. |
IndeterminateWriteError | Retry the same queue and task identity with return-existing. |
CallerTimeout | Continue waiting later with the same handle if the result retention window permits. |
CursorExpired | Reconcile durable state, then resume from an acceptable cursor. |
HistoryCursorExpired | Surface the gap, then use earliestCursor if the reader accepts resuming at the oldest retained entry. |
HistoryUnavailable | Stop polling this history; a separately retained result may still be available through wait. |
ProgressWriteError | Inspect reason; an indeterminate append may already exist, so do not blindly replay it. |
ResultExpired | Read the result from an application-owned durable store if longer retention is required. |
LeaseLost | Stop treating the attempt as owner; do not acknowledge it again. |
SchemaIdentityMismatch | Restore the matching schema/version or migrate stored data explicitly. |