What causes "Artifact exceeds the {self.max_content_nodes} node limit" in zylon-ai/private-gpt?

Raise the max_content_nodes setting if the deployment legitimately handles larger artifacts.

zylon-ai/private-gpt · error · ContentRequestLimitError

Artifact exceeds the {self.max_content_nodes} node limit

Error message

Artifact exceeds the {self.max_content_nodes} node limit

What it means

ContentRequestLimitError raised while flattening a document tree: the iterative stack walk has collected more than max_content_nodes nodes. This is a hard safety cap (self.max_content_nodes) preventing unbounded memory use on huge artifacts, checked incrementally as nodes are appended.

Source

Thrown at private_gpt/server/content/content_service.py:184

        return cast(TreeNode, root_nodes[0]) if root_nodes else None

    def _filter_tree_nodes(
        self,
        root: TreeNode,
        include: list[type[NodeType]] | None = None,
        exclude: list[type[NodeType]] | None = None,
        node_ids: list[str] | None = None,
        include_children: bool = True,
        include_ancestors: bool = False,
    ) -> Generator[str, None, None]:
        """Flatten tree and apply type filters."""
        all_nodes: list[TreeNode] = []
        stack = [root]
        while stack:
            node = stack.pop()
            all_nodes.append(node)
            if len(all_nodes) > self.max_content_nodes:
                raise ContentRequestLimitError(
                    f"Artifact exceeds the {self.max_content_nodes} node limit"
                )
            stack.extend(reversed(node.children))
        node_map = {node.id_: node for node in all_nodes}

        nodes_to_include: set[str] | None = None

        if node_ids:
            node_ids_set = set(node_ids)
            nodes_to_include = set()

            for node_id in node_ids_set:
                if node_id in node_map:
                    node = node_map[node_id]
                    nodes_to_include.add(node_id)

                    if include_children:
                        descendants = list(reversed(node.children))

View on GitHub (pinned to 4a030776a3)

Solutions

Raise the max_content_nodes setting if the deployment legitimately handles larger artifacts.
Use context_filter.artifacts / node_ids / include-exclude filters so only the needed subtree is flattened.
Re-ingest the source with coarser chunking to reduce node count.

Example fix

# before
nodes = list(service._flatten_tree(root))  # 200k-node artifact, cap 100k

# after
nodes = list(service._flatten_tree(root, node_ids=['sec-3'], include_children=True))  # targeted subtree

Defensive patterns

Strategy: validation

Validate before calling

total = count_nodes(root)
if total > service.max_content_nodes:
    raise ValueError(f'artifact too large ({total} nodes); filter it first')

Try / catch

try:
    nodes = list(flatten_tree(root, node_ids=target_ids))
except ContentRequestLimitError:
    nodes = list(flatten_tree(root, node_ids=target_ids[:10]))  # narrow scope

Prevention

Pass node_ids/include filters instead of flattening whole artifacts
Size max_content_nodes to your real documents at deployment
Coarsen chunking at ingestion if artifacts create huge node counts

When it happens

Trigger: Calling the tree-flattening path (get content / context building) with an artifact whose total node count exceeds the configured max_content_nodes.

Common situations: Very large ingested documents (whole-book splits, deep HTML trees); defaults tuned for small docs; sudden increase in document granularity (per-paragraph nodes) pushing counts over the cap.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/eba7a7802f3ca974. Report an issue: GitHub.