@temporalio/client/src/errors.ts

Temporal.io SDK Client sub-package

import type { ServiceError as GrpcServiceError } from '@grpc/grpc-js';
import { status } from '@grpc/grpc-js';
import type { RetryState } from '@temporalio/common';
import { isError, isRecord, SymbolBasedInstanceOfError } from '@temporalio/common/lib/type-helpers';

/**
 * Generic Error class for errors coming from the service
 */
@SymbolBasedInstanceOfError('ServiceError')
export class ServiceError extends Error {
  public readonly cause?: Error;

  constructor(message: string, opts?: { cause: Error }) {
    super(message);
    this.cause = opts?.cause;
  }
}

/**
 * Thrown by the client while waiting on Workflow execution result if execution
 * completes with failure.
 *
 * The failure type will be set in the `cause` attribute.
 *
 * For example if the workflow is cancelled, `cause` will be set to
 * {@link CancelledFailure}.
 */
@SymbolBasedInstanceOfError('WorkflowFailedError')
export class WorkflowFailedError extends Error {
  public constructor(
    message: string,
    public readonly cause: Error | undefined,
    public readonly retryState: RetryState
  ) {
    super(message);
  }
}

/**
 * Thrown by the client while waiting on Workflow Update result if Update
 * completes with failure.
 */
@SymbolBasedInstanceOfError('WorkflowUpdateFailedError')
export class WorkflowUpdateFailedError extends Error {
  public constructor(
    message: string,
    public readonly cause: Error | undefined
  ) {
    super(message);
  }
}

/**
 * Thrown by the client if the Update call timed out or was cancelled.
 * This doesn't mean the update itself was timed out or cancelled.
 */
@SymbolBasedInstanceOfError('WorkflowUpdateRPCTimeoutOrCancelledError')
export class WorkflowUpdateRPCTimeoutOrCancelledError extends Error {
  public readonly cause?: Error;

  public constructor(message: string, opts?: { cause: Error }) {
    super(message);
    this.cause = opts?.cause;
  }
}

/**
 * Thrown the by client while waiting on Workflow execution result if Workflow
 * continues as new.
 *
 * Only thrown if asked not to follow the chain of execution (see {@link WorkflowOptions.followRuns}).
 */
@SymbolBasedInstanceOfError('WorkflowExecutionContinuedAsNewError')
export class WorkflowContinuedAsNewError extends Error {
  public constructor(
    message: string,
    public readonly newExecutionRunId: string
  ) {
    super(message);
  }
}

/**
 * Thrown when the requested Activity could not be found.
 */
@SymbolBasedInstanceOfError('ActivityNotFoundError')
export class ActivityNotFoundError extends Error {}

/**
 * Thrown by {@link AsyncCompletionClient} when trying to complete or heartbeat
 * an Activity for any reason apart from {@link ActivityNotFoundError}.
 */
@SymbolBasedInstanceOfError('ActivityCompletionError')
export class ActivityCompletionError extends Error {}

/**
 * Thrown by {@link AsyncCompletionClient.heartbeat} when the Workflow has
 * requested to cancel the reporting Activity.
 */
@SymbolBasedInstanceOfError('ActivityCancelledError')
export class ActivityCancelledError extends Error {}

/**
 * Thrown by {@link AsyncCompletionClient.heartbeat} when the reporting Activity
 * has been paused.
 */
@SymbolBasedInstanceOfError('ActivityPausedError')
export class ActivityPausedError extends Error {}

/**
 * Thrown by {@link AsyncCompletionClient.heartbeat} when the reporting Activity
 * has been reset.
 */
@SymbolBasedInstanceOfError('ActivityResetError')
export class ActivityResetError extends Error {}

/**
 * Thrown by the {@link ActivityClient} while waiting on Activity execution result if execution completes with failure.
 * The failure is stored in the `cause` property.
 *
 * @experimental Standalone Activities are experimental. APIs may be subject to change.
 */
@SymbolBasedInstanceOfError('ActivityExecutionFailedError')
export class ActivityExecutionFailedError extends Error {
  constructor(
    message: string,
    public readonly cause: Error | undefined,
    public readonly activityId: string,
    public readonly runId?: string
  ) {
    super(message);
  }
}

/**
 * Thrown when starting an Activity failed because another Activity with the same ID already exists and reusing the ID
 * is not allowed under chosen ID reuse policy and ID conflict policy. See {@link ActivityOptions.idReusePolicy} and
 * {@link ActivityOptions.idConflictPolicy}.
 *
 * @experimental Standalone Activities are experimental. APIs may be subject to change.
 */
@SymbolBasedInstanceOfError('ActivityExecutionAlreadyStartedError')
export class ActivityExecutionAlreadyStartedError extends Error {
  constructor(
    message: string,
    /**
     * ID of the Activity that failed to start.
     */
    public readonly activityId: string,
    /**
     * Run ID of the existing Activity execution with the same Activity ID.
     */
    public readonly runId: string
  ) {
    super(message);
  }
}

/**
 * Returns true if the provided error is a {@link GrpcServiceError}.
 */
export function isGrpcServiceError(err: unknown): err is GrpcServiceError {
  return (
    isError(err) &&
    typeof (err as GrpcServiceError)?.details === 'string' &&
    isRecord((err as GrpcServiceError).metadata)
  );
}

/**
 * Returns true if the provided error or its cause is a {@link GrpcServiceError} with code DEADLINE_EXCEEDED.
 *
 * @see {@link Connection.withDeadline}
 */
export function isGrpcDeadlineError(err: unknown): err is Error {
  while (isError(err)) {
    if (isGrpcServiceError(err) && (err as GrpcServiceError).code === status.DEADLINE_EXCEEDED) {
      return true;
    }
    err = (err as any).cause;
  }
  return false;
}

/**
 * Returns true if the provided error or its cause is a {@link GrpcServiceError} with code CANCELLED.
 *
 * @see {@link Connection.withAbortSignal}
 */
export function isGrpcCancelledError(err: unknown): err is Error {
  while (isError(err)) {
    if (isGrpcServiceError(err) && (err as GrpcServiceError).code === status.CANCELLED) {
      return true;
    }
    err = (err as any).cause;
  }
  return false;
}

/**
 * @deprecated Use `isGrpcServiceError` instead
 */
export const isServerErrorResponse = isGrpcServiceError;