Child object must be a an array of RelatedNodeInfo objects

Error message

Child object must be a an array of RelatedNodeInfo objects

What it means

The BaseNode.childNodes getter reads the CHILD relationship, which must be an array of RelatedNodeInfo objects. If the value is missing or a single object (not an array), the getter throws because children are inherently a collection.

Source

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

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

/**
 * TextNode is the default node type for text.
 */
export class TextNode<T extends Metadata = Metadata> extends BaseNode<T> {
  text: string;

  startCharIdx?: number;
  endCharIdx?: number;
  metadataSeparator: string;

View on GitHub (pinned to 75dd419e61)

Solutions

Assign an array even for one child: relationships[NodeRelationship.CHILD] = [childInfo].
Guard undefined: only read childNodes after relationships are populated (e.g. by a splitter or fromJSON).
Normalize deserialized data so CHILD is always an array (possibly empty).

Example fix

// before
node.relationships[NodeRelationship.CHILD] = childInfo;
// after
node.relationships[NodeRelationship.CHILD] = [childInfo];

Defensive patterns

Strategy: type-guard

Validate before calling

const rel = node.relationships[NodeRelationship.CHILD];
const children = Array.isArray(rel) ? rel : rel !== undefined ? [rel] : [];

Type guard

const isRelatedNodeInfoArray = (v: unknown): v is RelatedNodeInfo[] =>
  Array.isArray(v) && v.every(x => x !== null && typeof x === 'object' && 'nodeId' in x);

Try / catch

let children: RelatedNodeInfo[] = [];
try {
  children = node.childNodes;
} catch (e) {
  if (e instanceof Error && e.message.includes('Child object must be')) {
    const rel = node.relationships[NodeRelationship.CHILD];
    children = rel !== undefined && !Array.isArray(rel) ? [rel] : [];
  } else throw e;
}

Prevention

Always wrap child assignments in an array, even for a single child.
Initialize CHILD as [] when creating nodes you'll link later.
Normalize deserialized maps so CHILD is always an array.

When it happens

Trigger: Accessing node.childNodes when relationships[NodeRelationship.CHILD] is undefined or was set to a single RelatedNodeInfo object instead of an array.

Common situations: Assigning one child without wrapping it in an array (symmetry mistake with source/prev/next/parent), or partial deserialization that drops the CHILD entry.

Related errors

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