errors

Classes

ContractError

Defined in: packages/contract/src/errors-impl.ts:75

A typed domain error declared on a contract's errors map.

One class covers every declared error; the errorName field is the per-error discriminant (it equals the key in the contract's errors map and the ApplicationFailure.type on the wire). Narrow a union with it:

if (result.isErr() && result.error instanceof ContractError) {
  switch (result.error.errorName) {
    case "PaymentDeclined":
      result.error.data; // { reason: string }
  }
}

The unthrown _tag ("@temporal-contract/ContractError") discriminates a ContractError from the other tagged errors in a Result's error channel (e.g. via result.match({ errCases: (m) => m.with(P.tag("@temporal-contract/ContractError"), …) })); errorName then narrows to the concrete declared error.

Extends

TaggedErrorInstance<"@temporal-contract/ContractError", { cause?: unknown; data: TData; errorName: TName; }>

Type Parameters

Type Parameter	Default type
`TName` extends `string`	`string`
`TData`	`unknown`

Constructors

Constructor

new ContractError<TName, TData>(args): ContractError<TName, TData>;

Defined in: packages/contract/src/errors-impl.ts:88

Parameters

Parameter	Type
`args`	{ `cause?`: `unknown`; `data`: `TData`; `errorName`: `TName`; `message`: `string`; }
`args.cause?`	`unknown`
`args.data`	`TData`
`args.errorName`	`TName`
`args.message`	`string`

Returns

ContractError<TName, TData>

Overrides

TaggedError(
  CONTRACT_ERROR_TAG,
  { name: "ContractError" },
)<{
  / Declared error name — the ApplicationFailure.type discriminator. /
  errorName: TName;
  / Structured payload validated against the declared data schema. /
  data: TData;
  cause?: unknown;
}>.constructor

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
`_tag`	`readonly`	`"@temporal-contract/ContractError"`	-	`TaggedError( CONTRACT_ERROR_TAG, { name: "ContractError" }, )._tag`	node_modules/.pnpm/unthrown@5.7.0/node_modules/unthrown/dist/index.d.mts:2011
`cause?`	`public`	`unknown`	-	`TaggedError( CONTRACT_ERROR_TAG, { name: "ContractError" }, ).cause`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
`data`	`readonly`	`TData`	Structured payload validated against the declared `data` schema.	`TaggedError( CONTRACT_ERROR_TAG, { name: "ContractError" }, ).data`	packages/contract/src/errors-impl.ts:82
`errorName`	`readonly`	`TName`	Declared error name — the `ApplicationFailure.type` discriminator.	`TaggedError( CONTRACT_ERROR_TAG, { name: "ContractError" }, ).errorName`	packages/contract/src/errors-impl.ts:80
`message`	`public`	`string`	-	`TaggedError( CONTRACT_ERROR_TAG, { name: "ContractError" }, ).message`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
`name`	`public`	`string`	-	`TaggedError( CONTRACT_ERROR_TAG, { name: "ContractError" }, ).name`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
`stack?`	`public`	`string`	-	`TaggedError( CONTRACT_ERROR_TAG, { name: "ContractError" }, ).stack`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

TechnicalError

Defined in: packages/contract/src/errors-impl.ts:43

Error for technical/runtime failures that cannot be prevented by TypeScript — connection failures, missing runtime capabilities, worker bundling errors. These are unmodeled infrastructure faults, never anticipated domain failures, so they ride the Defect channel: the creation factories (TypedClient.create, TypedWorker.create) surface them as a Defect whose cause is a TechnicalError instance (inspect via match's defect handler, recoverDefect, or tapDefect) — this class never appears in a Result's modeled E channel.

The class is retained (and still exported) so the descriptive message and cause survive for logging; it is only ever used as a defect's cause.

Extends

TaggedErrorInstance<"@temporal-contract/TechnicalError", { cause?: unknown; }>

Constructors

Constructor

new TechnicalError(message, cause?): TechnicalError;

Defined in: packages/contract/src/errors-impl.ts:48

Parameters

Parameter	Type
`message`	`string`
`cause?`	`unknown`

Returns

TechnicalError

Overrides

TaggedError(TECHNICAL_ERROR_TAG, {
  name: "TechnicalError",
})<{
  cause?: unknown;
}>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
`_tag`	`readonly`	`"@temporal-contract/TechnicalError"`	`TaggedError(TECHNICAL_ERROR_TAG, { name: "TechnicalError", })._tag`	node_modules/.pnpm/unthrown@5.7.0/node_modules/unthrown/dist/index.d.mts:2011
`cause?`	`public`	`unknown`	`TaggedError(TECHNICAL_ERROR_TAG, { name: "TechnicalError", }).cause`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
`message`	`public`	`string`	`TaggedError(TECHNICAL_ERROR_TAG, { name: "TechnicalError", }).message`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
`name`	`public`	`string`	`TaggedError(TECHNICAL_ERROR_TAG, { name: "TechnicalError", }).name`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
`stack?`	`public`	`string`	`TaggedError(TECHNICAL_ERROR_TAG, { name: "TechnicalError", }).stack`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Type Aliases

AnyContractError

type AnyContractError = ContractError<string, unknown>;

Defined in: packages/contract/src/errors-impl.ts:99

Widest ContractError instantiation — useful as a constraint or for instanceof-style narrowing before discriminating on errorName.

ApplicationFailureLike

type ApplicationFailureLike = object;

Defined in: packages/contract/src/errors-impl.ts:192

Structural view of a Temporal ApplicationFailure — the fields the rehydrator reads. Kept structural so this package doesn't depend on @temporalio/common; callers perform the instanceof ApplicationFailure check on their side and pass the instance in.

Properties

Property	Modifier	Type	Defined in
`details?`	`readonly`	readonly `unknown`[] \| `null`	packages/contract/src/errors-impl.ts:195
`message?`	`readonly`	`string`	packages/contract/src/errors-impl.ts:194
`type?`	`readonly`	`string` \| `null`	packages/contract/src/errors-impl.ts:193

ContractErrorConstructors

type ContractErrorConstructors<TErrors> = { [K in keyof TErrors & string]: TErrors[K] extends { data: AnySchema } ? (data: InferErrorDataInput<TErrors[K]>, options?: ContractErrorOptions) => ContractError<K, InferErrorDataInput<TErrors[K]>> : (options?: ContractErrorOptions) => ContractError<K, undefined> };

Defined in: packages/contract/src/errors-impl.ts:135

Map of typed error constructors for a declared errors map, handed to implementations (activity helpers / workflow context). Errors with a data schema take the payload first; data-less errors take only options.

Type Parameters

Type Parameter
`TErrors` extends `Record`<`string`, `ErrorDefinition`>

ContractErrorInputUnion

type ContractErrorInputUnion<TErrors> = { [K in keyof TErrors & string]: ContractError<K, InferErrorDataInput<TErrors[K]>> }[keyof TErrors & string];

Defined in: packages/contract/src/errors-impl.ts:126

Producer-side union of ContractError instances for a declared errors map — data is typed with each schema's input (pre-transform) shape, matching what the typed constructors build.

Type Parameters

Type Parameter
`TErrors` extends `Record`<`string`, `ErrorDefinition`>

ContractErrorOptions

type ContractErrorOptions = object;

Defined in: packages/contract/src/errors-impl.ts:106

Per-instance options accepted by a typed error constructor. The nonRetryable flag is deliberately absent: retry semantics live on the contract's ErrorDefinition, not the call site.

Properties

Property	Modifier	Type	Defined in
`cause?`	`readonly`	`unknown`	packages/contract/src/errors-impl.ts:108
`message?`	`readonly`	`string`	packages/contract/src/errors-impl.ts:107

ContractErrorUnion

type ContractErrorUnion<TErrors> = { [K in keyof TErrors & string]: ContractError<K, InferErrorData<TErrors[K]>> }[keyof TErrors & string];

Defined in: packages/contract/src/errors-impl.ts:117

Consumer-side union of ContractError instances for a declared errors map — data is typed with each schema's output (post-transform) shape. This is the union surfaced on the error channel of workflow-side activity calls and client-side workflow results.

Type Parameters

Type Parameter
`TErrors` extends `Record`<`string`, `ErrorDefinition`>

RehydrationMiss

type RehydrationMiss = object;

Defined in: packages/contract/src/errors-impl.ts:224

Diagnostic payload describing a rehydration miss: a failure whose type matched a declared error name but that could not be rehydrated as the typed ContractError and degraded to the caller's generic failure classification.

Properties

Property	Modifier	Type	Description	Defined in
`errorName`	`readonly`	`string`	The declared error name that `failure.type` matched.	packages/contract/src/errors-impl.ts:226
`failure`	`readonly`	`ApplicationFailureLike`	The failure that was being rehydrated.	packages/contract/src/errors-impl.ts:239
`issues?`	`readonly`	`ReadonlyArray`<`StandardSchemaV1.Issue`>	Validation issues when `reason` is `"data-validation-failed"`.	packages/contract/src/errors-impl.ts:237
`reason`	`readonly`	`"data-validation-failed"` \| `"missing-wire-marker"`	Why rehydration degraded: - `"data-validation-failed"` — the declared `data` schema rejected `details[0]` (schema drift or a foreign failure with a payload); - `"missing-wire-marker"` — a data-less declared error without the CONTRACT_ERROR_WIRE_MARKER, i.e. most likely an unrelated `ApplicationFailure` reusing the declared name as its `type`.	packages/contract/src/errors-impl.ts:235

Variables

CONTRACT_ERROR_WIRE_MARKER

const CONTRACT_ERROR_WIRE_MARKER: object;

Defined in: packages/contract/src/errors-impl.ts:206

Wire-envelope marker carried at details[1] of every ApplicationFailure produced from a ContractError (details[0] stays the data payload). It marks the failure as temporal-contract provenance, versioned for future envelope evolution, so the rehydrator can tell a genuine contract error from an unrelated ApplicationFailure that merely reuses a declared error name as its type string.

Type Declaration

Name	Type	Default value	Defined in
`$tc`	`1`	`1`	packages/contract/src/errors-impl.ts:206

Functions

onRehydrationMiss()

function onRehydrationMiss(handler): void;

Defined in: packages/contract/src/errors-impl.ts:253

Register a module-level diagnostic hook invoked whenever a failure whose type matches a declared error name fails to rehydrate as a typed ContractError (see RehydrationMiss). The degrade-to-generic behavior is unchanged — this only makes it observable. The worker and client packages wire this into their loggers; pass undefined to unregister. A throwing handler is swallowed: diagnostics must never break error classification.

Parameters

Parameter	Type
`handler`	((`miss`) => `void`) \| `undefined`

Returns

void

References

CONTRACT_ERROR_TAG

Re-exports CONTRACT_ERROR_TAG

TECHNICAL_ERROR_TAG

Re-exports TECHNICAL_ERROR_TAG

errors ​

Classes ​

ContractError ​

Extends ​

Type Parameters ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Overrides ​

Properties ​

TechnicalError ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Overrides ​

Properties ​

Type Aliases ​

AnyContractError ​

ApplicationFailureLike ​

Properties ​

ContractErrorConstructors ​

Type Parameters ​

ContractErrorInputUnion ​

Type Parameters ​

ContractErrorOptions ​

Properties ​

ContractErrorUnion ​

Type Parameters ​

RehydrationMiss ​

Properties ​

Variables ​

CONTRACT_ERROR_WIRE_MARKER ​

Type Declaration ​

Functions ​

onRehydrationMiss() ​

Parameters ​

Returns ​

References ​

CONTRACT_ERROR_TAG ​

TECHNICAL_ERROR_TAG ​

errors

Classes

ContractError

Extends

Type Parameters

Constructors

Constructor

Parameters

Returns

Overrides

Properties

TechnicalError

Extends

Constructors

Constructor

Parameters

Returns

Overrides

Properties

Type Aliases

AnyContractError

ApplicationFailureLike

Properties

ContractErrorConstructors

Type Parameters

ContractErrorInputUnion

Type Parameters

ContractErrorOptions

Properties

ContractErrorUnion

Type Parameters

RehydrationMiss

Properties

Variables

CONTRACT_ERROR_WIRE_MARKER

Type Declaration

Functions

onRehydrationMiss()

Parameters

Returns

References

CONTRACT_ERROR_TAG

TECHNICAL_ERROR_TAG