hook-conflict

This error occurs when you try to create a hook with a token that is already in use by another active workflow run. Hook tokens must be unique across all running workflows in your project.

Error Message

Hook token "<token>" is already in use by another workflow

Hooks use tokens to identify incoming webhook payloads. When you create a hook with createHook({ token: "my-token" }), the Workflow runtime reserves that token for your workflow run. If another workflow run is already using that token, a conflict occurs.

This typically happens when:

Two workflows start simultaneously with the same hardcoded token
A previous workflow run is still waiting for a hook when a new run tries to use the same token

Common Causes

Hardcoded Token Values

// Error - multiple concurrent runs will conflict
export async function processPayment() {
  "use workflow";

  const hook = createHook({ token: "payment-hook" }); 
  // If another run is already waiting on "payment-hook", this will fail
  const payment = await hook;
}

Solution: Use unique tokens that include the run ID or other unique identifiers.

import { createHook } from "workflow";

export async function processPayment(orderId: string) {
  "use workflow";

  // Include unique identifier in token
  const hook = createHook({ token: `payment-${orderId}` }); 
  const payment = await hook;
}

Omitting the Token (Auto-generated)

The safest approach is to let the Workflow runtime generate a unique token automatically:

import { createHook } from "workflow";

export async function processPayment() {
  "use workflow";

  const hook = createHook(); // Auto-generated unique token
  console.log(`Send webhook to token: ${hook.token}`);
  const payment = await hook;
}

Handling Hook Conflicts

When a hook conflict occurs, awaiting the hook will throw a HookConflictError. The error exposes the token that conflicted and, for current worlds, the run ID that currently owns it. conflictingRunId remains optional for compatibility with older persisted events and world implementations, so guard it before delegating:

import { createHook } from "workflow";
import { HookConflictError } from "@workflow/errors";

export async function processPayment(orderId: string) {
  "use workflow";

  const hook = createHook({ token: `payment-${orderId}` });

  try {
    const payment = await hook; 
    return { success: true, payment };
  } catch (error) {
    if (HookConflictError.is(error)) { 
      // Another workflow is already processing this order
      console.log(`Conflicting token: ${error.token}`);
      if (error.conflictingRunId) {
        console.log(`Active run: ${error.conflictingRunId}`);
      }
      return {
        success: false,
        reason: "duplicate-processing",
        token: error.token,
        runId: error.conflictingRunId
      };
    }
    throw error; // Re-throw other errors
  }
}

This pattern is useful when you want to detect duplicate processing inside the workflow. Runtime APIs such as resumeHook() and getRun() must be called outside workflow functions, for example from an API route or in a step.

Delegate to the Active Run

In idempotency flows, a conflict means another active run already owns the hook token. You can return the duplicate-processing payload from the workflow, resume the active hook to deliver the payload to the existing run, then use getRun(result.runId) to wait for, stream, or cancel the active run:

import { getRun, resumeHook, start } from "workflow/api";
import { processPayment } from "@/workflows/process-payment";

type ProcessPaymentResult =
  | { success: true; payment: unknown }
  | {
      success: false;
      reason: "duplicate-processing";
      token: string;
      runId?: string;
    };

export async function POST(request: Request) {
  const { orderId, payment } = await request.json();
  const run = await start(processPayment, [orderId]);
  const result = (await run.returnValue) as ProcessPaymentResult;

  if (
    result.success === false &&
    result.reason === "duplicate-processing" &&
    result.runId
  ) {
    await resumeHook(result.token, payment); 
    const activeRun = getRun(result.runId); 

    return Response.json({
      delegatedToRunId: activeRun.runId,
      result: await activeRun.returnValue
    });
  }

  return Response.json(result);
}

If the caller needs live output instead of the final result, return activeRun.getReadable() from the same branch. If the duplicate request should replace the active work, call await activeRun.cancel() after inspecting the run.

When Hook Tokens Are Released

Hook tokens are automatically released when:

The workflow run completes (successfully or with an error)
The workflow run is cancelled
The hook is explicitly disposed

After a workflow completes, its hook tokens become available for reuse by other workflows.

Best Practices

Use auto-generated tokens when possible - they are guaranteed to be unique
Include unique identifiers if you need custom tokens (order ID, user ID, etc.)
Avoid reusing the same token across multiple concurrent workflow runs
Consider using webhooks (createWebhook) if you need a fixed, predictable URL that can receive multiple payloads

Hooks - Learn more about using hooks in workflows
getRun - Retrieve or control the active run
resumeHook - Deliver data to the active hook
createWebhook - Alternative for fixed webhook URLs