Graphify-Labs/graphify · error · ValueError

--root {root} matched 0 of {len(by_file)} source files (sour

Error message

--root {root} matched 0 of {len(by_file)} source files (source_file paths are stored repo-relative, e.g. {sample!r})

What it means

Raised in the tree builder (graphify/tree_html.py) when an explicitly passed --root matched zero of the source files being laid out. source_file paths in the graph are stored repo-relative, so passing an absolute checkout path (or any prefix that matches nothing) would otherwise silently flatten the whole tree with every file attached to the root; the guard turns that into an explicit error (#2534). A partial match is fine and does not raise.

Source

Thrown at graphify/tree_html.py:169

        if len(sym_children) > max_children:
            extra = len(sym_children) - max_children
            sym_children = sym_children[:max_children] + [
                _make_truncation_leaf(extra),
            ]
        file_node = {
            "name": src_path.name,
            "total_count": len(sym_children) or 1,
            "children": sym_children,
        }
        parent_dir["children"].append(file_node)

    # An explicit --root that matches NOTHING would silently flatten the whole
    # hierarchy (every file attaches to the root); the common case is passing an
    # absolute checkout path while source_file is stored repo-relative (#2534).
    # A PARTIAL match stays fine — files outside the root legitimately attach flat.
    if explicit_root and matched_files == 0:
        sample = min(by_file)
        raise ValueError(
            f"--root {root} matched 0 of {len(by_file)} source files "
            f"(source_file paths are stored repo-relative, e.g. {sample!r})"
        )

    # Sort each dir's children + propagate total_count up.
    def _finalise(d: Dict[str, Any]) -> int:
        kids = d.get("children") or []
        kids.sort(key=lambda c: (
            0 if (c.get("children") and len(c["children"]) > 0) else 1,
            c["name"].lower(),
        ))
        if not kids:
            return d.get("total_count") or 1
        n = 0
        for c in kids:
            n += _finalise(c)
        d["total_count"] = n or 1
        return d["total_count"]

View on GitHub (pinned to 7fe58b0b0f)

Solutions

1. Pass the repo-relative prefix instead of an absolute path, e.g. --root src/ rather than /home/me/repo/src.
2. Compare your --root against the sample shown in the error message (min(by_file)) to see the expected path format.
3. If you meant 'no filter', drop --root entirely rather than guessing a root.
4. For embedding in HTML with a different base, remap source_file values before generating the tree.

Example fix

# before
graphify tree-html --root /home/me/repos/project/src

# after
graphify tree-html --root src

from pathlib import Path

def root_matches_any(root: str, by_file: dict[str, dict]) -> int:
    return sum(1 for f in by_file if f.startswith(root))

# prefer repo-relative roots; reject ones that match nothing
root = "src" if root_matches_any("src", by_file) else None

def is_repo_relative_root(root: str, sample_file: str) -> bool:
    # stored paths are repo-relative, so absolute roots never prefix-match
    return not Path(root).is_absolute() and sample_file.startswith(root.split("/")[0] + "/") is not None

try:
    tree = build_tree(data, root=args.root)
except ValueError as e:
    if "matched 0 of" in str(e):
        args.root = None  # no filter instead of a wrong absolute filter
        tree = build_tree(data, root=args.root)
    else:
        raise

When it happens

Trigger: Invoking the tree/HTML export with --root /home/me/repos/project while nodes store source_file as 'src/foo.py' (relative), so the absolute prefix matches 0 of len(by_file) files; any --root whose string prefix does not overlap any stored path.

Common situations: Users habitually passing absolute paths on the command line; scripts generating --root from os.getcwd(); graphs built on one machine and rendered on another with a different checkout location.

Related errors

• graph not found: {source_path}
• repo '{repo_tag}' not in global graph
• No git repository found at or above {path.resolve()}
• Claude Code CLI not found on $PATH
• gh CLI not found or not authenticated. Run: gh auth login

AI-assisted analysis of Graphify-Labs/graphify@7fe58b0b0f (2026-08-14). Data as JSON: /api/errors/37ab4e7bb3be344d. Report an issue: GitHub.