mastra-ai/mastra · error

Next object must be a single RelatedNodeInfo object

Error message

Next object must be a single RelatedNodeInfo object

What it means

The BaseNode.nextNode getter reads the NEXT relationship and expects a single RelatedNodeInfo object. A node can have only one next neighbor, so an array in that slot throws.

Source

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

    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];

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

    return relationship;
  }

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

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set relationships[NodeRelationship.NEXT] to one RelatedNodeInfo object.
2. Fix deserialization/normalization so scalar relationships are not wrapped in arrays.
3. Re-run the splitter's linking logic rather than hand-editing NEXT pointers.

Example fix

// before
node.relationships[NodeRelationship.NEXT] = [nextInfo, otherInfo];
// after
node.relationships[NodeRelationship.NEXT] = nextInfo;

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

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

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

When it happens

Trigger: Accessing node.nextNode (e.g. during highlight updates / traversal) when relationships[NodeRelationship.NEXT] holds an array.

Common situations: Manually relinking chunks after edits, or deserialization code that array-wraps all relationship values uniformly.

Related errors

• Source object must be a single RelatedNodeInfo object
• Previous object must be a single RelatedNodeInfo object
• Parent object must be a single RelatedNodeInfo object
• Child object must be a an array of RelatedNodeInfo objects
• Unknown strategy: ${strategy}

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