Parent object must be a single RelatedNodeInfo object

Error message

Parent object must be a single RelatedNodeInfo object

What it means

The BaseNode.parentNode getter reads the PARENT relationship and expects a single RelatedNodeInfo object. A node has at most one parent, so an array value throws.

Source

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

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

    if (!Array.isArray(relationship)) {
      throw new Error('Child object must be a an array of RelatedNodeInfo objects');
    }

    return relationship;
  }

  abstract generateHash(): string;
}

View on GitHub (pinned to 75dd419e61)

Solutions

Assign a single RelatedNodeInfo to relationships[NodeRelationship.PARENT].
If multiple candidates exist, pick/store one parent; model siblings via CHILD on the parent node instead.
Normalize relationship maps during deserialization before use.

Example fix

// before
node.relationships[NodeRelationship.PARENT] = [parentInfo];
// after
node.relationships[NodeRelationship.PARENT] = parentInfo;

Defensive patterns

Strategy: type-guard

Validate before calling

const rel = node.relationships[NodeRelationship.PARENT];
const parent = 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 parent;
try {
  parent = node.parentNode;
} catch (e) {
  if (e instanceof Error && e.message.includes('Parent object must be')) {
    const rel = node.relationships[NodeRelationship.PARENT];
    parent = Array.isArray(rel) ? rel[0] : undefined;
  } else throw e;
}

Prevention

Enforce single-parent invariants in your indexing code.
Model multiple relations via the parent's CHILD array, not multiple parents.
Add a schema check on stored relationship maps before constructing nodes.

When it happens

Trigger: Accessing node.parentNode when relationships[NodeRelationship.PARENT] was assigned an array of RelatedNodeInfo.

Common situations: Hierarchical/chunked indexing code that mistakenly pushes multiple parents, or generic serialization that wraps every relationship in an array.

Related errors

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