跳到主要内容

BranchNotMaterializedError

Defined in: packages/rxdb-plugin-working-tree/src/working-tree/branch-materialization.ts:123

物化依据不足，整次尝试以 branch_not_materialized 全量回滚（FR-044）。

Remarks​

八个成因的分辨力全在这个类上，所以它不是一个裸 RxDBError：stage_missing 要重新拉一遍， stage_incomplete 可以接着上次拉，intent_drift 要换一份意图重来，stage_tampered 要把这份 staging 整个丢掉重拉（接着拉只会把坏页留在原地），page_conflict 说明另一路正在续同一份 staging（它本身没坏，重判一次续用位置再接着拉），target_already_materialized 说明这条分支 本来就不该走这条路；source_unavailable 与 source_failed 与库里的状态无关——前者说的是 这条连接上还没有快照来源（同步插件没装或没连上），后者说的是来源方这一次没给出来（多半是 网络），已落库的页留着，下一次切换接着拉。合并成一个错误码之后，调用方只能一律重来。

抛出时 staging 不被顺手删掉：那半份 payload 连同它的 scopeManifest 正是诊断「上一次为什么 没接上」需要的东西。清理是 FR-044 单列的一条能力（discardMaterializationAttempt）， 是调用方的决定，不是判定的副作用。

Extends​

Constructors​

Constructor​

new BranchNotMaterializedError(
   branchId, 
   attemptId, 
   reason, 
   detail, 
   cause?
): BranchNotMaterializedError;

Defined in: packages/rxdb-plugin-working-tree/src/working-tree/branch-materialization.ts:143

Parameters​

ParameterTypeDescription
branchIdstring物化失败的目标分支 id
attemptIdstring | null本次尝试的 attempt id，可据此清理或续用；一次都还没开始时是 null
reasonBranchNotMaterializedReason成因
detailstring人读的补充说明
cause?unknown来源方抛出的原始错误；只有 source_failed 带它

Returns​

BranchNotMaterializedError

Remarks​

attemptId 可空是因为 source_unavailable（以及冻结意图时就失败的 source_failed）在 任何 attempt 开始之前就判定了：那一刻库里连一行 staging 都没有。给它编一个不存在的 id 的话，用户拿着它去 discardMaterializationAttempt 会静默成功（清理是幂等的）， 于是「这个 id 指向什么」永远问不出答案。

cause 原样挂着而不是折进 detail：网络错误的类型与状态码是调用方决定「稍后重试」还是 「提示用户」的依据，折成字符串之后就只剩一句话了。

Overrides​

RxDBError.constructor

Properties​

attemptId​

readonly attemptId: string | null;

Defined in: packages/rxdb-plugin-working-tree/src/working-tree/branch-materialization.ts:145

本次尝试的 attempt id，可据此清理或续用；一次都还没开始时是 null

branchId​

readonly branchId: string;

Defined in: packages/rxdb-plugin-working-tree/src/working-tree/branch-materialization.ts:144

物化失败的目标分支 id

cause?​

readonly optional cause?: unknown;

Defined in: packages/rxdb-plugin-working-tree/src/working-tree/branch-materialization.ts:148

来源方抛出的原始错误；只有 source_failed 带它

Inherited from​

RxDBError.cause

code​

readonly code: CommitErrorCode = CommitErrorCode.branch_not_materialized;

Defined in: packages/rxdb-plugin-working-tree/src/working-tree/branch-materialization.ts:125

错误码，恒为 CommitErrorCode.branch_not_materialized

detail​

readonly detail: string;

Defined in: packages/rxdb-plugin-working-tree/src/working-tree/branch-materialization.ts:147

人读的补充说明

message​

message: string;

Defined in: node_modules/.pnpm/typescript@6.0.3_patch_hash=ef3c2292deb88eb14130359d5acc1febc0226af46b7b945db6c7250c6cb4efbb/node_modules/typescript/lib/lib.es5.d.ts:1075

Inherited from​

RxDBError.message

name​

name: string;

Defined in: node_modules/.pnpm/typescript@6.0.3_patch_hash=ef3c2292deb88eb14130359d5acc1febc0226af46b7b945db6c7250c6cb4efbb/node_modules/typescript/lib/lib.es5.d.ts:1074

Inherited from​

RxDBError.name

reason​

readonly reason: BranchNotMaterializedReason;

Defined in: packages/rxdb-plugin-working-tree/src/working-tree/branch-materialization.ts:146

成因

stack?​

optional stack?: string;

Defined in: node_modules/.pnpm/typescript@6.0.3_patch_hash=ef3c2292deb88eb14130359d5acc1febc0226af46b7b945db6c7250c6cb4efbb/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from​

RxDBError.stack

stackTraceLimit​

static stackTraceLimit: number;

Defined in: node_modules/.pnpm/@types+node@26.6.3/node_modules/@types/node/globals.d.ts:67

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​

RxDBError.stackTraceLimit

Methods​

captureStackTrace()​

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@26.6.3/node_modules/@types/node/globals.d.ts:51

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​

ParameterType
targetObjectobject
constructorOpt?Function

Returns​

void

Inherited from​

RxDBError.captureStackTrace

prepareStackTrace()​

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.pnpm/@types+node@26.6.3/node_modules/@types/node/globals.d.ts:55

Parameters​

ParameterType
errError
stackTracesCallSite[]

Returns​

any

See​

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

Inherited from​

RxDBError.prepareStackTrace