run-llama/llama_index · error · ImportError

`treelib` package is missing. Please install it by using `pi

Error message

`treelib` package is missing. Please install it by using `pip install treelib`.

What it means

Raised by llama-index-instrumentation's SimpleSpanHandler._get_trace_trees when the optional `treelib` dependency cannot be imported. The handler builds hierarchical trace trees from completed/dropped spans and uses treelib's Tree structure to render them; without the package installed the ImportError is re-raised with an install hint. Note the raise also discards the original ImportError context.

Source

Thrown at llama-index-instrumentation/src/llama_index_instrumentation/span_handlers/simple.py:100

        if not children:
            return acc
        updated_spans = [s for s in spans if s not in children]

        children_trees = [
            self._build_tree_by_parent(
                parent=c, acc=[c], spans=[s for s in updated_spans if c != s]
            )
            for c in children
        ]

        return acc + reduce(lambda x, y: x + y, children_trees)

    def _get_trace_trees(self) -> List["Tree"]:
        """Method for getting trace trees."""
        try:
            from treelib import Tree
        except ImportError as e:
            raise ImportError(
                "`treelib` package is missing. Please install it by using "
                "`pip install treelib`."
            )

        all_spans = self.completed_spans + self.dropped_spans
        for s in all_spans:
            if s.parent_id is None:
                continue
            if not any(ns.id_ == s.parent_id for ns in all_spans):
                warnings.warn(f"Parent with id {s.parent_id} missing from spans")
                s.parent_id += "-MISSING"
                all_spans.append(SimpleSpan(id_=s.parent_id, parent_id=None))

        parents = self._get_parents()
        span_groups = []
        for p in parents:
            this_span_group = self._build_tree_by_parent(
                parent=p, acc=[p], spans=[s for s in all_spans if s != p]

View on GitHub (pinned to afd0fef371)

Solutions

1. pip install treelib in the same environment/venv that runs the instrumentation code
2. Add treelib to your requirements.txt/pyproject optional extras if you rely on trace trees
3. If you don't need trace rendering, avoid the code path that calls _get_trace_trees

Example fix

# before
handler = SimpleSpanHandler()
# ... later, rendering traces raises ImportError

# after
pip install treelib
handler = SimpleSpanHandler()

def treelib_available() -> bool:
    try:
        import treelib  # noqa: F401
        return True
    except ImportError:
        return False

try:
    trees = handler._get_trace_trees()
except ImportError as e:
    if "treelib" in str(e):
        logger.warning("treelib missing; trace rendering disabled")
    else:
        raise

When it happens

Trigger: Calling span-handler APIs that render traces (e.g. printing/exporting trace trees via SimpleSpanHandler) in an environment where `pip install treelib` was never run. The try/except ImportError around `from treelib import Tree` converts the missing module into this actionable ImportError.

Common situations: Installing llama-index-instrumentation without its visualization extras; running in a slim Docker/CI image where optional deps are pruned; upgrading environments and losing manually installed treelib.

Related errors

• Cannot add two handlers of the same type {type(new_handler)}
• Cannot import cohere package, please `pip install cohere`.
• Please install yfiles_jupyter_graphs to visualize the graph:
• Please install scikit-learn to use this feature.
• You need to install jsonpath-ng to use this function!

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/8592cf5a52d02a2e. Report an issue: GitHub.