Context

The Hatchet Context class provides helper methods and useful data to tasks at runtime. It is passed as the second argument to all task blocks.

There are two types of context classes you'll encounter:

• Hatchet::Context - The standard context for regular tasks with methods for logging, task output retrieval, cancellation, and more.
• Hatchet::DurableContext - An extended context for durable tasks that includes additional methods for durable execution like sleep_for and wait_for.

Context

Context object passed to task execution blocks.

Provides access to workflow run metadata, parent task outputs, logging, cancellation, and other runtime capabilities.

workflow.task(:step2, parents: [step1]) do |input, ctx|
  parent_result = ctx.task_output(step1)
  { "sum" => parent_result["value"] + 1 }
end

Methods

Attributes

additional_metadata

Additional metadata attached to this run.

Returns:

attempt_number

Current attempt number (retry_count + 1)

Returns:

deps

Resolved dependency values.

Returns:

filter_payload

Filter payload for event-triggered workflows.

Returns:

priority

Task priority.

Returns:

retry_count

Current retry count (0 on first attempt)

Returns:

step_run_id

The step run ID.

Returns:

worker_id

The worker ID assigned by the server.

Returns:

workflow_run_id

The workflow run ID.

Returns:

Functions

task_output

Get the output of a parent task.

Parameters:

Returns:

was_skipped?

Check if a parent task was skipped.

Parameters:

Returns:

log

Log a message via the Hatchet logging system. Sends the log to the server via gRPC if an event client is available.

Parameters:

cancel

Cancel the current workflow run.

Batch tasks share one context across every buffered member, so there is no single task run to cancel; instead this sends a batch CANCELLED event covering every member of the batch.

cancelled?

Check if the task has been cancelled.

Returns:

refresh_timeout

Refresh the execution timeout for this task.

Parameters:

release_slot

Release the worker slot before the task completes. Useful for tasks that have a resource-intensive phase followed by a lighter phase.

put_stream

Put a stream chunk for real-time streaming output.

Parameters:

task_run_errors

Get errors from upstream task runs (used in on_failure tasks)

Returns:

get_task_run_error

Get the error from a specific upstream task (used in on_failure tasks)

Parameters:

Returns:

worker

Access the worker context for worker-level operations. The returned WorkerContext exposes id (the worker id), labels (the current worker labels), and upsert_labels to add or update worker labels on the server at runtime.

Returns:

DurableContext

Bases: Hatchet::Context

Extended context for durable tasks that supports sleep and event-waiting across task suspensions. All methods and attributes of Context are also available.

Durable tasks can be suspended and resumed by the Hatchet engine, allowing long-running workflows that survive process restarts.

hatchet.durable_task(name: "my_task") do |input, ctx|
  ctx.sleep_for(duration: 60) # sleep for 60 seconds
end

hatchet.durable_task(name: "my_task") do |input, ctx|
  result = ctx.wait_for("event", Hatchet::UserEventCondition.new(event_key: "user:update"))
end

Methods

Functions

sleep_for

Sleep for a specified duration. The task is suspended and resumed by the engine after the duration expires, so no worker slot is blocked while sleeping (subject to the task's eviction policy).

Parameters:

Returns:

wait_for

Wait for a condition to be met (event or sleep). The task is suspended and resumed when the condition is satisfied.

Parameters:

Returns: