# Class: ExecutionError

Error thrown when an operation execution fails. Use for statement failures, canceled operations, or unexpected states.

## Example[​](#example "Direct link to Example")

```typescript
throw new ExecutionError("Statement failed: syntax error");
throw new ExecutionError("Statement was canceled");

```

## Extends[​](#extends "Direct link to Extends")

* [`AppKitError`](./docs/api/appkit/Class.AppKitError.md)

## Constructors[​](#constructors "Direct link to Constructors")

### Constructor[​](#constructor "Direct link to Constructor")

```ts
new ExecutionError(message: string, options?: {
  cause?: Error;
  clientMessage?: string;
  context?: Record<string, unknown>;
  errorCode?: string;
}): ExecutionError;

```

#### Parameters[​](#parameters "Direct link to Parameters")

| Parameter                | Type                                                                                                                  |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `message`                | `string`                                                                                                              |
| `options?`               | { `cause?`: `Error`; `clientMessage?`: `string`; `context?`: `Record`<`string`, `unknown`>; `errorCode?`: `string`; } |
| `options.cause?`         | `Error`                                                                                                               |
| `options.clientMessage?` | `string`                                                                                                              |
| `options.context?`       | `Record`<`string`, `unknown`>                                                                                         |
| `options.errorCode?`     | `string`                                                                                                              |

#### Returns[​](#returns "Direct link to Returns")

`ExecutionError`

#### Overrides[​](#overrides "Direct link to Overrides")

[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`constructor`](./docs/api/appkit/Class.AppKitError.md#constructor)

## Properties[​](#properties "Direct link to Properties")

### \_clientMessage?[​](#_clientmessage "Direct link to _clientMessage?")

```ts
protected readonly optional _clientMessage: string;

```

Client-safe error message. When set, callers serializing the error to a client (SSE, HTTP body) MUST prefer `clientMessage` over `message` — `message` may contain raw upstream / SDK text including statement fragments, internal object names, and correlation IDs.

Subclasses can set this in their constructor for a fixed sanitized string. When unset, `clientMessage` defaults to a generic per-code string (see the getter), and the raw `message` is kept server-side only.

#### Inherited from[​](#inherited-from "Direct link to Inherited from")

[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`_clientMessage`](./docs/api/appkit/Class.AppKitError.md#_clientmessage)

***

### cause?[​](#cause "Direct link to cause?")

```ts
readonly optional cause: Error;

```

Optional cause of the error

#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")

[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`cause`](./docs/api/appkit/Class.AppKitError.md#cause)

***

### code[​](#code "Direct link to code")

```ts
readonly code: "EXECUTION_ERROR" = "EXECUTION_ERROR";

```

Error code for programmatic error handling

#### Overrides[​](#overrides-1 "Direct link to Overrides")

[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`code`](./docs/api/appkit/Class.AppKitError.md#code)

***

### context?[​](#context "Direct link to context?")

```ts
readonly optional context: Record<string, unknown>;

```

Additional context for the error

#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")

[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`context`](./docs/api/appkit/Class.AppKitError.md#context)

***

### errorCode?[​](#errorcode "Direct link to errorCode?")

```ts
readonly optional errorCode: string;

```

Structured error code from the upstream source (typically the warehouse's `error_code` for statement-level failures, or the SDK's `ApiError.errorCode` for HTTP failures). Preserved through wrapping so callers can branch on a stable identifier without substring-matching the message.

***

### isRetryable[​](#isretryable "Direct link to isRetryable")

```ts
readonly isRetryable: false = false;

```

Whether this error type is generally safe to retry

#### Overrides[​](#overrides-2 "Direct link to Overrides")

[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`isRetryable`](./docs/api/appkit/Class.AppKitError.md#isretryable)

***

### statusCode[​](#statuscode "Direct link to statusCode")

```ts
readonly statusCode: 500 = 500;

```

HTTP status code suggestion (can be overridden)

#### Overrides[​](#overrides-3 "Direct link to Overrides")

[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`statusCode`](./docs/api/appkit/Class.AppKitError.md#statuscode)

## Accessors[​](#accessors "Direct link to Accessors")

### clientMessage[​](#clientmessage "Direct link to clientMessage")

#### Get Signature[​](#get-signature "Direct link to Get Signature")

```ts
get clientMessage(): string;

```

Execution errors default to a generic message — the raw warehouse / SDK text in `.message` often includes statement fragments, internal paths, and correlation IDs. UI code should branch on `errorCode` (`RESULT_TOO_LARGE_FOR_JSON_FALLBACK`, `NOT_IMPLEMENTED`, etc.) and not on the human string.

##### Returns[​](#returns-1 "Direct link to Returns")

`string`

#### Overrides[​](#overrides-4 "Direct link to Overrides")

[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`clientMessage`](./docs/api/appkit/Class.AppKitError.md#clientmessage)

## Methods[​](#methods "Direct link to Methods")

### toJSON()[​](#tojson "Direct link to toJSON()")

```ts
toJSON(): Record<string, unknown>;

```

Convert error to JSON for logging/serialization. Sensitive values in context are automatically redacted.

#### Returns[​](#returns-2 "Direct link to Returns")

`Record`<`string`, `unknown`>

#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")

[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`toJSON`](./docs/api/appkit/Class.AppKitError.md#tojson)

***

### toString()[​](#tostring "Direct link to toString()")

```ts
toString(): string;

```

Create a human-readable string representation

#### Returns[​](#returns-3 "Direct link to Returns")

`string`

#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")

[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`toString`](./docs/api/appkit/Class.AppKitError.md#tostring)

***

### canceled()[​](#canceled "Direct link to canceled()")

```ts
static canceled(): ExecutionError;

```

Create an execution error for canceled operation

#### Returns[​](#returns-4 "Direct link to Returns")

`ExecutionError`

***

### missingData()[​](#missingdata "Direct link to missingData()")

```ts
static missingData(dataType: string): ExecutionError;

```

Create an execution error for missing data

#### Parameters[​](#parameters-1 "Direct link to Parameters")

| Parameter  | Type     |
| ---------- | -------- |
| `dataType` | `string` |

#### Returns[​](#returns-5 "Direct link to Returns")

`ExecutionError`

***

### resultsClosed()[​](#resultsclosed "Direct link to resultsClosed()")

```ts
static resultsClosed(): ExecutionError;

```

Create an execution error for closed/expired results

#### Returns[​](#returns-6 "Direct link to Returns")

`ExecutionError`

***

### statementFailed()[​](#statementfailed "Direct link to statementFailed()")

```ts
static statementFailed(
   errorMessage?: string, 
   errorCode?: string, 
   clientMessage?: string): ExecutionError;

```

Create an execution error for statement failure.

#### Parameters[​](#parameters-2 "Direct link to Parameters")

| Parameter        | Type     | Description                                                                                                                                                                                       |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `errorMessage?`  | `string` | Human-readable error from the warehouse / SDK. Goes into `.message` for server logs only — *never* echoed to the client. Pass `clientMessage` explicitly if a sanitized text should reach the UI. |
| `errorCode?`     | `string` | Structured code (e.g. "INVALID\_PARAMETER\_VALUE") to preserve through wrapping. Optional. Forwarded on SSE error payloads so UI can branch on it instead of substring-matching `error`.          |
| `clientMessage?` | `string` | Optional client-safe replacement for `.message`. Defaults to "Query execution failed" via the `clientMessage` getter. Set this only when the upstream text is known-safe.                         |

#### Returns[​](#returns-7 "Direct link to Returns")

`ExecutionError`

***

### unknownState()[​](#unknownstate "Direct link to unknownState()")

```ts
static unknownState(state: string): ExecutionError;

```

Create an execution error for unknown state

#### Parameters[​](#parameters-3 "Direct link to Parameters")

| Parameter | Type     |
| --------- | -------- |
| `state`   | `string` |

#### Returns[​](#returns-8 "Direct link to Returns")

`ExecutionError`