Queue Config

Queue config settings let you control how Queue Steps handle retries, concurrency, and backoff. Motia provides sensible defaults, so you only configure what you need.

How It Works

Add config to your queue trigger:

import { type Handlers, type StepConfig } from 'motia'
 
export const config = {
  name: 'SendEmail',
  description: 'Send email with retry support',
  triggers: [
    {
      type: 'queue',
      topic: 'email.requested',
      config: {
        maxRetries: 5,
        visibilityTimeout: 60
      }
    },
  ],
  flows: ['notifications'],
} as const satisfies StepConfig

Configuration Options

Property	Type	Default	Description
`type`	`string`	`standard`	Queue type: `standard` or `fifo`
`maxRetries`	`number`	3	Number of retry attempts on failure
`visibilityTimeout`	`number`	900	Seconds before message becomes visible again
`delaySeconds`	`number`	0	Delay before processing (0-900 seconds)
`concurrency`	`number`	-	Max parallel message processing per topic
`backoffType`	`string`	-	Retry backoff strategy (e.g., `exponential`)
`backoffDelayMs`	`number`	-	Base delay in ms for retry backoff

FIFO Queues

FIFO queues guarantee exactly-once processing and maintain message order within a group.

import { type Handlers, type StepConfig } from 'motia'
 
export const config = {
  name: 'ProcessOrder',
  description: 'Process orders in FIFO order',
  triggers: [
    {
      type: 'queue',
      topic: 'order.created',
      config: { type: 'fifo' }
    },
  ],
  flows: ['orders'],
} as const satisfies StepConfig

Message Group ID

When enqueuing to FIFO queues, pass a messageGroupId:

export const handler: Handlers<typeof config> = async ({ request }, { enqueue }) => {
  const { orderId, customerId } = request.body
 
  await enqueue({
    topic: 'order.created',
    data: { orderId, customerId },
    messageGroupId: customerId
  })
}

The messageGroupId ensures events are processed in order within that group.

Default Values

If you don't specify config on a queue trigger, Motia uses these defaults:

{
  type: 'standard',
  maxRetries: 3,
  visibilityTimeout: 900,
  delaySeconds: 0
}

How It Works

Configuration Options

FIFO Queues

Message Group ID

Default Values

On this page