Class: OsfqlError

Defined in: src/errors.ts:610

An OSFQL program the engine refused or failed to run.

Remarks

Thrown by OsfqlClient.execute and OsfqlClient.preview for every OsfqlErrorResponse body except a deadline. Narrow on errorType:

parse / compile (HTTP 400) — rewrite the program;
execution (HTTP 422) — it failed while running. When the failure is a typed write refusal, refusal carries the code and the concrete repairs;
row_cap (HTTP 422) — one materialisation outgrew maxRows; add a LIMIT, narrow the pattern, or send a larger maxRows. Nothing was written;
refused (HTTP 400 / 404 / 409) — a DROP SORT the guarded sort delete refused, or an ALTER SORT … PARENTS move the engine refused. An ALTER SORT … PARENTS that names an unknown or foreign parent is a 400 refusal (Cannot reparent sort 'S': parent sort X does not exist), while an unknown subject sort stays an execution 422;
lock_timeout (HTTP 503, OsfqlClient.execute only) — other writers kept the tenant’s knowledge base locked until the request deadline, and nothing ran. Retry the program as is, or send a larger timeoutMs. This error is an OsfqlError, not a ServiceUnavailableError: a caller that branched on ServiceUnavailableError for /osfql must branch on errorType === 'lock_timeout' instead. The transport’s own 503 retry (retryOn503) still applies before this error is thrown.

A program abandoned at its timeoutMs deadline throws DeadlineExceededError instead (HTTP 504, error_type: "timeout"), because every route’s deadline answers that one contract.

A program with a DROP SORT or an ALTER SORT … PARENTS beside another statement is refused (HTTP 400) before anything runs, with atomicRefusal.code drop_sort_not_alone / alter_sort_not_alone — the same code OsfqlClient.preview reports.

A refused DROP SORT (errorType: 'refused') carries the sort-delete refusal in sortDeleteRefusal, as sortDeleteRefusalOf(error) reads it.

status, body and headers are those of the engine’s answer, as on every ApiError; message is the engine’s own sentence.

Example

try {
  await client.osfql.execute('UPSERT customer(tier: "silver");');
} catch (e) {
  if (e instanceof OsfqlError && e.refusal) {
    console.error(e.refusal.code, e.refusal.repairs[0]?.rewrite);
  } else if (e instanceof OsfqlError && e.errorType === 'row_cap') {
    console.error(`raise maxRows above ${e.maxRows}`);
  } else if (e instanceof OsfqlError && e.errorType === 'lock_timeout') {
    // the knowledge base stayed locked and nothing ran: retry as is
  } else if (e instanceof DeadlineExceededError) {
    // retry, or send a larger timeoutMs
  }
}

Extends

ApiError

Constructors

Constructor

new OsfqlError(status, body, headers, failure): OsfqlError

Defined in: src/errors.ts:628

Parameters

status

number

body

unknown

headers

Headers

failure

OsfqlFailure

Returns

OsfqlError

Overrides

ApiError.constructor

Properties

atomicRefusal

readonly atomicRefusal: OsfqlAtomicRefusal | undefined

Defined in: src/errors.ts:626

Why the program was refused before anything ran — a DROP SORT or an ALTER SORT … PARENTS beside another statement. Set only when errorType is refused for that reason.

body

readonly body: unknown

Defined in: src/errors.ts:55

Parsed response body.

Inherited from

ApiError.body

cause?

optional cause?: unknown

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26

Inherited from

ApiError.cause

errorCode

readonly errorCode: string | undefined

Defined in: src/errors.ts:53

Backend error code (from response body error field), if present.

Inherited from

ApiError.errorCode

errorType

readonly errorType: OsfqlErrorType

Defined in: src/errors.ts:614

The class of the failure (error_type on the wire).

headers

readonly headers: Headers

Defined in: src/errors.ts:57

Response headers.

Inherited from

ApiError.headers

maxRows

readonly maxRows: number | undefined

Defined in: src/errors.ts:618

The row cap the program ran under. Set only when errorType is row_cap.

message

message: string

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

ApiError.message

name

name: string = 'OsfqlError'

Defined in: src/errors.ts:611

Overrides

ApiError.name

refusal

readonly refusal: OsfqlRefusal | undefined

Defined in: src/errors.ts:616

The typed write refusal, when the failure is one.

sortDeleteRefusal

readonly sortDeleteRefusal: SortDeleteRefusalDto | undefined

Defined in: src/errors.ts:620

The coded refusal of a DROP SORT. Set only when errorType is refused.

stack?

optional stack?: string

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

ApiError.stack

status

readonly status: number

Defined in: src/errors.ts:51

HTTP status code.

Inherited from

ApiError.status

stackTraceLimit

static stackTraceLimit: number

Defined in: node_modules/.pnpm/@types+node@24.13.3/node_modules/@types/node/globals.d.ts:68

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

ApiError.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Defined in: node_modules/.pnpm/@types+node@24.13.3/node_modules/@types/node/globals.d.ts:52

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

ApiError.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

Defined in: node_modules/.pnpm/@types+node@24.13.3/node_modules/@types/node/globals.d.ts:56

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

ApiError.prepareStackTrace