Task routing

By default, Hatchet dispatches each task to any available worker that has registered the corresponding workflow. You can override this behavior to pin tasks to specific workers or control execution order.

Sticky assignment

Sticky assignment ensures that all tasks within a workflow run execute on the same worker. This is useful when your tasks share in-process state — for example, a loaded ML model or an in-memory cache — that would be expensive to reconstruct on a different worker. Set sticky on the workflow or standalone task definition. Two strategies are available:

Strategy	Behavior
`StickyStrategy.SOFT`	Prefer the same worker. Falls back to any available worker if the original is unavailable.
`StickyStrategy.HARD`	Require the same worker. The task will not run unless the original worker is available.

Sticky workflow

Python
TypeScript
Go

worker.py

from hatchet_sdk import Context, EmptyModel, Hatchet, StickyStrategy

hatchet = Hatchet(debug=True)

sticky_workflow = hatchet.workflow(
    name="StickyWorkflow",
    # Specify a sticky strategy when declaring the workflow
    sticky=StickyStrategy.SOFT,
)


@sticky_workflow.task()
def step1a(input: EmptyModel, ctx: Context) -> dict:
    return {"worker": ctx.worker.id()}


@sticky_workflow.task()
def step1b(input: EmptyModel, ctx: Context) -> dict:
    return {"worker": ctx.worker.id()}

When sticky=StickyStrategy.SOFT is set on the workflow, Hatchet will try to route all tasks in the run to the same worker that picked up the first task.

workflow.ts

import { StickyStrategy } from '@hatchet/v1';
import { hatchet } from './hatchet-client';

export const sticky = hatchet.task({
  name: 'sticky',
  retries: 3,
  sticky: StickyStrategy.SOFT,
  fn: async (_, ctx) => {
    return { worker: ctx.worker.id() };
  },
});

main.go

import (
    "github.com/hatchet-dev/hatchet/pkg/client/types"
    hatchet "github.com/hatchet-dev/hatchet/sdks/go"
)

func StickyDag(client *hatchet.Client) *hatchet.Workflow {
    stickyDag := client.NewWorkflow("sticky-dag",
        hatchet.WithWorkflowStickyStrategy(types.StickyStrategy_SOFT),
    )

    _ = stickyDag.NewTask("sticky-task",
        func(ctx hatchet.Context, input StickyInput) (interface{}, error) {
            workerId := ctx.Worker().ID()
            return &StickyResult{Result: workerId}, nil
        },
    )

    return stickyDag
}

Sticky child workflows

You can propagate sticky assignment to child workflows spawned from within a task. Pass sticky=True when spawning the child to request that it run on the same worker as the parent.

Python
TypeScript
Go

worker.py

from hatchet_sdk import Context, EmptyModel, Hatchet, StickyStrategy, TriggerWorkflowOptions

hatchet = Hatchet(debug=True)

sticky_workflow = hatchet.workflow(name="StickyWorkflow", sticky=StickyStrategy.SOFT)
sticky_child_workflow = hatchet.workflow(name="StickyChildWorkflow", sticky=StickyStrategy.SOFT)


@sticky_workflow.task(parents=[step1a, step1b])
async def step2(input: EmptyModel, ctx: Context) -> dict:
    # Run a child workflow on the same worker
    ref = await sticky_child_workflow.aio_run_no_wait(
        options=TriggerWorkflowOptions(sticky=True)
    )
    await ref.aio_result()
    return {"worker": ctx.worker.id()}


@sticky_child_workflow.task()
def child(input: EmptyModel, ctx: Context) -> dict:
    return {"worker": ctx.worker.id()}

workflow.ts

import { StickyStrategy } from '@hatchet/v1';
import { hatchet } from './hatchet-client';
import { child } from '../child_workflows/workflow';

export const sticky = hatchet.task({
  name: 'sticky',
  retries: 3,
  sticky: StickyStrategy.SOFT,
  fn: async (_, ctx) => {
    // Specify a child workflow to run on the same worker
    const result = await child.run(
      { N: 1 },
      { sticky: true },
    );
    return { result };
  },
});

main.go

func Sticky(client *hatchet.Client) *hatchet.StandaloneTask {
    sticky := client.NewStandaloneTask("sticky-task",
        func(ctx worker.HatchetContext, input StickyInput) (*StickyResult, error) {
            // Run a child workflow on the same worker
            childWorkflow := Child(client)
            childResult, err := childWorkflow.Run(ctx, ChildInput{N: 1}, hatchet.WithRunSticky(true))
            if err != nil {
                return nil, err
            }

            var childOutput ChildResult
            err = childResult.Into(&childOutput)
            if err != nil {
                return nil, err
            }

            return &StickyResult{
                Result: fmt.Sprintf("child-result-%s", childOutput.Result),
            }, nil
        },
    )
    return sticky
}

Registering the worker

Python
TypeScript
Go

worker.py

def main() -> None:
    worker = hatchet.worker(
        "sticky-worker",
        slots=10,
        workflows=[sticky_workflow, sticky_child_workflow],
    )
    worker.start()

if __name__ == "__main__":
    main()

worker.ts

import { hatchet } from './hatchet-client';
import { sticky } from './workflow';

async function main() {
  const worker = await hatchet.worker('sticky-worker', {
    workflows: [sticky],
    slots: 10,
  });
  await worker.start();
}

if (require.main === module) {
  main();
}

main.go

worker, err := client.NewWorker(
    "sticky-worker",
    hatchet.WithWorkflows(StickyDag(client), Sticky(client)),
    hatchet.WithSlots(10),
)

For StickyStrategy.HARD, the task will fail with a scheduling error rather than fall back to another worker if the original worker is unavailable. Use SOFT unless your correctness requirements demand the same worker.

Task priority

When multiple tasks are queued, Hatchet uses priority to determine which ones are dispatched first. Higher values win. Set a default priority on the workflow or task definition:

Python
TypeScript
Go

high_priority_workflow = hatchet.workflow(
    name="HighPriorityWorkflow",
    default_priority=3,  # 1 (low) to 3 (high), default is 1
)

# Or on a standalone task
@hatchet.task(default_priority=3)
def urgent_task(input: EmptyModel, ctx: Context) -> dict:
    return {}

const urgentTask = hatchet.task({
  name: 'urgent-task',
  priority: 3,
  fn: async (input) => ({}),
});

// Priority is set per-run via WithRunPriority (see below)

You can also override priority at run time when triggering a task:

Python
TypeScript
Go

from hatchet_sdk import TriggerWorkflowOptions

my_task.run(
    options=TriggerWorkflowOptions(priority=3),
)

await myTask.run(input, { priority: 3 });

result, err := myTask.Run(
    ctx,
    input,
    hatchet.WithRunPriority(3),
)

Priority values range from 1 (lowest) to 3 (highest). The default is 1. Use priority sparingly — if everything is high priority, nothing is.

Desired worker labels at run time

You can target a specific worker at the point of triggering a task run by passing desired_worker_labels (Python / TypeScript) or WithDesiredWorkerLabels (Go). The scheduler will prefer — or require, if required=True — a worker whose labels match.

Python
TypeScript
Go

from hatchet_sdk import TriggerWorkflowOptions
from hatchet_sdk.labels import DesiredWorkerLabel

my_task.run(
    options=TriggerWorkflowOptions(
        desired_worker_label={
            "affinity": DesiredWorkerLabel(
                value="foo",
                required=True,
            ),
        }
    )
)

await affinityExampleTask.run(
  {},
  {
    desiredWorkerLabels: {
      affinity: {
        value: 'foo',
        required: true,
      },
    },
  },
);

result, err := affinityTask.Run(
    ctx,
    EmptyInput{},
    hatchet.WithDesiredWorkerLabels(map[string]*hatchet.DesiredWorkerLabel{
        "affinity": {
            Value:    "foo",
            Required: true,
        },
    }),
)

See Worker affinity for full details on label-based routing and comparators.

Next steps

Worker affinity

Label-based routing to direct tasks to workers with specific capabilities.

Workers overview

Configure slots, lifespan functions, and worker startup.

Get Started

Running Tasks

Flow Control

Workers

Observability

Self-Hosting

Sticky assignment

Sticky workflow

Sticky child workflows

Registering the worker

Task priority

Desired worker labels at run time

Next steps

Worker affinity

Workers overview

Build docs developers (and LLMs) love

Get Started

Running Tasks

Flow Control

Workers

Observability

Self-Hosting

​Sticky assignment

​Sticky workflow

​Sticky child workflows

​Registering the worker

​Task priority

​Desired worker labels at run time

​Next steps

Worker affinity

Workers overview

Build docs developers (and LLMs) love

Sticky assignment

Sticky workflow

Sticky child workflows

Registering the worker

Task priority

Desired worker labels at run time

Next steps