Previous object must be a single RelatedNodeInfo object

Error message

Previous object must be a single RelatedNodeInfo object

What it means

The BaseNode.prevNode getter reads the PREVIOUS relationship and expects a single RelatedNodeInfo object. An array in that slot is invalid — a node has at most one previous neighbor in the sequence.

Source

Thrown at packages/rag/src/document/schema/node.ts:43

  abstract getContent(): string;

  abstract getMetadataStr(): string;

  get sourceNode(): RelatedNodeInfo<T> | undefined {
    const relationship = this.relationships[NodeRelationship.SOURCE];

    if (Array.isArray(relationship)) {
      throw new Error('Source object must be a single RelatedNodeInfo object');
    }

    return relationship;
  }

  get prevNode(): RelatedNodeInfo<T> | undefined {
    const relationship = this.relationships[NodeRelationship.PREVIOUS];

    if (Array.isArray(relationship)) {
      throw new Error('Previous object must be a single RelatedNodeInfo object');
    }

    return relationship;
  }

  get nextNode(): RelatedNodeInfo<T> | undefined {
    const relationship = this.relationships[NodeRelationship.NEXT];

    if (Array.isArray(relationship)) {
      throw new Error('Next object must be a single RelatedNodeInfo object');
    }

    return relationship;
  }

  get parentNode(): RelatedNodeInfo<T> | undefined {
    const relationship = this.relationships[NodeRelationship.PARENT];

View on GitHub (pinned to 75dd419e61)

Solutions

Set relationships[NodeRelationship.PREVIOUS] to a single RelatedNodeInfo object, not an array.
Normalize deserialized relationship maps before constructing nodes.
Build prev/next links via the splitter/node linking utilities instead of manual assignment.

Example fix

// before
node.relationships[NodeRelationship.PREVIOUS] = [prevInfo];
// after
node.relationships[NodeRelationship.PREVIOUS] = prevInfo;

Defensive patterns

Strategy: type-guard

Validate before calling

const rel = node.relationships[NodeRelationship.PREVIOUS];
const prev = rel !== undefined && !Array.isArray(rel) ? rel : undefined;

Type guard

const isSingleRelatedNodeInfo = (v: unknown): v is RelatedNodeInfo =>
  v !== null && typeof v === 'object' && !Array.isArray(v) && 'nodeId' in v;

Try / catch

let prev;
try {
  prev = node.prevNode;
} catch (e) {
  if (e instanceof Error && e.message.includes('Previous object must be')) {
    const rel = node.relationships[NodeRelationship.PREVIOUS];
    prev = Array.isArray(rel) ? rel[0] : undefined;
  } else throw e;
}

Prevention

Store PREVIOUS/NEXT as single objects, reserving arrays for CHILD only.
Write one shared deserializer that unwraps arrays for scalar relationships.
Test round-trip serialize/parse to catch shape drift.

When it happens

Trigger: Accessing node.prevNode when relationships[NodeRelationship.PREVIOUS] was set to an array of RelatedNodeInfo.

Common situations: Uniformly serializing all relationships as arrays, or code that reuses the CHILD (array) structure for PREVIOUS/NEXT links when re-linking split chunks.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/eeb47813343fa4fd. Report an issue: GitHub.