workflow/docs/api-reference/workflow-errors/hook-conflict-error.mdx

Workflow SDK - Build durable, resilient, and observable workflows

---
title: HookConflictError
description: Thrown when creating a hook, or starting a run with a hook, whose token another workflow run owns.
type: reference
summary: Catch HookConflictError when a hook token is already owned by another workflow run, including a duplicate start({ experimental_hook }).
related:
  - /docs/api-reference/workflow/create-hook
  - /docs/foundations/hooks
  - /docs/errors/hook-conflict
  - /docs/foundations/idempotency
---

`HookConflictError` is thrown when creating a hook, or calling [`start({ experimental_hook })`](/docs/api-reference/workflow-api/start#prevent-duplicate-starts), with a token that another workflow run owns. From `start()` it always carries `conflictingRunId`, and no run was created for the duplicate. The owner may still be running, or may have finished while an `experimental_minRetention` holds the token. To deliver the duplicate's data instead, resume the owner's start Hook: see [Start or route to the owner](/docs/foundations/idempotency#start-or-route-to-the-owner).

When creating a hook, it means the token is already in use by another active workflow run. Hook tokens must be unique across all running workflows. See the [hook-conflict](/docs/errors/hook-conflict) error guide for resolution strategies. To take the token over instead, create the hook with [`experimental_force: true`](/docs/api-reference/workflow/create-hook#take-over-a-token-another-run-holds).

```typescript lineNumbers
import { HookConflictError } from "workflow/errors"
declare function startApprovalWorkflow(token: string): Promise<void>; // @setup
declare const token: string; // @setup

try {
  await startApprovalWorkflow(token);
} catch (error) {
  if (HookConflictError.is(error)) { // [!code highlight]
    console.error(
      `Token "${error.token}" already in use by run ${error.conflictingRunId}`
    );
  }
}
```

## API signature

### Properties

<TSDoc
definition={`
interface HookConflictError {
  /** The hook token that conflicted. */
  token: string;
  /** The run ID of the workflow currently holding the token, when known. */
  conflictingRunId?: string;
  /** The error message. */
  message: string;
}
export default HookConflictError;`}
/>

### Static methods

#### `HookConflictError.is(value)`

Type-safe check for `HookConflictError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.

```typescript
import { HookConflictError } from "workflow/errors"
declare const error: unknown; // @setup

if (HookConflictError.is(error)) {
  // error is typed as HookConflictError
}
```