# How to Debug Issues Within the Graph Module in Hivemind

> Debug Hivemind graph module issues by instrumenting the VFS stack and using the bundled test suite to isolate and reproduce failures. Learn how to effectively troubleshoot your graph module.

- Repository: [Activeloop/hivemind](https://github.com/activeloopai/hivemind)
- Tags: how-to-guide
- Published: 2026-06-11

---

**You can debug Hivemind's graph module by instrumenting the virtual filesystem (VFS) stack—starting with command parsing in [`graph-command.ts`](https://github.com/activeloopai/hivemind/blob/main/graph-command.ts), proceeding through the dispatcher in [`vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/vfs-handler.ts), and ending at the specific renderers in `src/graph/render/`—while using the bundled test suite under `tests/shared/graph/` to isolate and reproduce failures.**

The graph module in `activeloopai/hivemind` implements a **virtual filesystem (VFS)** that synthesizes text views of code-graph snapshots. When commands like `cat ~/.deeplake/memory/graph/find/foo` return errors such as `No local graph for this worktree yet` or unexpected `not-found` messages, you must trace execution through three distinct architectural layers to identify the root cause.

## Understanding the Graph Module Architecture

The graph subsystem consists of three layers that handle every VFS read request.

### Command Parsing Layer

Located in [`src/graph/graph-command.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/graph-command.ts), the **`parseReadTargetPath`** function transforms shell commands (e.g., `cat ...`, `ls ...`) into virtual paths. The **`tryGraphRead`** function then forwards these paths to the dispatcher. Parsing logic includes pipe handling constraints around lines 52-62.

### VFS Dispatcher Layer

The **`handleGraphVfs`** function in [`src/graph/vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/vfs-handler.ts) (lines 48-62) receives the virtual path and routes it to the appropriate renderer. It returns a `not-found` result if the path is invalid or a `no-graph` result if the snapshot cannot be loaded.

### Renderer Layer

Individual renderers in `src/graph/render/` (such as [`render/find.ts`](https://github.com/activeloopai/hivemind/blob/main/render/find.ts) and [`render/show.ts`](https://github.com/activeloopai/hivemind/blob/main/render/show.ts)) read the graph snapshot and emit markdown text for specific endpoints like `index`, `find`, `show`, and `query`.

## Step-by-Step Debugging Workflow

Follow this sequence to isolate bugs in any of the three layers.

### 1. Reproduce the Issue Locally

Start by triggering the specific graph read that fails. For example:

```bash
cat ~/.deeplake/memory/graph/find/foo

```

If you see errors like `No local graph for this worktree yet` or `not-found`, you have identified the entry point for debugging.

### 2. Instrument the Command Parser

Add `console.debug` statements to [`src/graph/graph-command.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/graph-command.ts) to trace how the shell command is parsed. Insert logging near the top of `parseReadTargetPath` (around lines 49-55):

```typescript
export function parseReadTargetPath(rewrittenCommand: string): string | null {
  console.debug('[graph-command] raw command →', rewrittenCommand);
  const cmd = rewrittenCommand.replace(/\s+2>\S+/g, "").trim();
  // ...
}

```

Re-run the `cat` command. If the function returns `null`, the parser rejected the command due to unsupported flags or pipe handling issues (see logic around lines 52-62).

### 3. Verify the VFS Dispatcher

Confirm the virtual path reaches `handleGraphVfs` by adding debug output in `tryGraphRead` before the dispatcher call (around lines 110-114):

```typescript
export function tryGraphRead(rewrittenCommand: string, cwd: string): string | null {
  // ...
  const virtualPath = parseReadTargetPath(rewrittenCommand);
  console.debug('[graph-command] virtualPath →', virtualPath);
  // ...
}

```

If the path is missing the `/graph/` prefix or is malformed, the bug lies in the parser's normalization logic.

### 4. Inspect the VFS Handler

Drill into [`src/graph/vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/vfs-handler.ts) to see which renderer is invoked or if the request fails early. Add logging at the start of `handleGraphVfs` (line 48):

```typescript
export function handleGraphVfs(subpath: string, cwd: string): GraphVfsResult {
  console.debug('[vfs-handler] subpath →', subpath, 'cwd →', cwd);
  // ...
}

```

Check if the function returns a `not-found` result (lines 56-62) or reaches a specific renderer like `renderFind`.

### 5. Debug Snapshot Loading

If you encounter a `no-graph` result (lines 70-85), the snapshot cannot be loaded. The **`loadSnapshotOrError`** helper (lines 62-87) attempts to read from `repoDir`. Add path logging:

```typescript
const snapPath = join(baseDir, "snapshots", `${fileBase}.json`);
console.debug('[vfs-handler] snapPath →', snapPath);

```

Common causes include:

- **Cannot derive repo identity**: The identity module cannot hash the current working directory (missing Git metadata).
- **No local graph for this worktree yet**: The graph has not been built; run `hivemind graph build` or `hivemind graph pull`.
- **Snapshot file missing on disk**: The JSON file was removed or `repoDir` has incorrect permissions.

### 6. Unit Test the Failing Path

The test suite in `tests/shared/graph/` validates VFS behavior. Run specific tests to isolate the failure:

```bash
npm test -- tests/shared/graph/vfs-handler.test.ts

```

To simulate a corrupted snapshot, edit the temporary [`.find-handles.json`](https://github.com/activeloopai/hivemind/blob/main/.find-handles.json) file created by the test harness and re-run. The `try...catch` block at lines 111-115 in [`vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/vfs-handler.ts) surfaces thrown errors as `no-graph` results.

### 7. Check CLI Build Logs

If the issue originates during graph construction rather than VFS reads, use the CLI with the **`--dry-run`** flag. This outputs sub-command execution details and lock file locations (`.graph-on-stop.log`). The hook in [`src/hooks/graph-on-stop.ts`](https://github.com/activeloopai/hivemind/blob/main/src/hooks/graph-on-stop.ts) emits messages like `gate: FIRE` or `decideGate threw` when the build process fails.

### 8. Clean Up and Rebuild

After fixing the bug, remove stale snapshots and rebuild:

```bash
rm -rf $(hivemind graph repo-dir)
hivemind graph build
cat ~/.deeplake/memory/graph/find/foo

```

## Common Failure Patterns

| Symptom | Location | Resolution |
|---------|----------|------------|
| `null` path from parser | [`graph-command.ts`](https://github.com/activeloopai/hivemind/blob/main/graph-command.ts) (lines 52-62) | Check for unsupported pipe characters or flags in the command |
| `not-found` result | [`vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/vfs-handler.ts) (lines 56-62) | Verify the subpath matches an existing renderer endpoint |
| Cannot derive repo identity | Identity resolution logic | Ensure the directory is a Git repository with valid metadata |
| Missing snapshot errors | [`vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/vfs-handler.ts) (lines 70-85) | Run `hivemind graph build` to generate the JSON snapshot |

## Summary

- **Debug the graph module** by tracing the VFS stack from `parseReadTargetPath` through `handleGraphVfs` to the specific renderer in `src/graph/render/`.
- **Instrument code** with `console.debug` in [`src/graph/graph-command.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/graph-command.ts) and [`src/graph/vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/vfs-handler.ts) to trace command-to-path transformations and dispatcher routing.
- **Handle snapshot errors** by verifying the repository identity, checking file permissions in the `repoDir`, and rebuilding with `hivemind graph build`.
- **Validate fixes** using the unit test suite in `tests/shared/graph/` and the `--dry-run` CLI flag for build-time issues.

## Frequently Asked Questions

### How do I enable verbose logging for graph commands?

Insert `console.debug` statements at the entry points of `parseReadTargetPath` in [`src/graph/graph-command.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/graph-command.ts) and `handleGraphVfs` in [`src/graph/vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/vfs-handler.ts). Re-run the shell command that triggered the error and inspect the output to see the raw command string, parsed virtual path, and current working directory at each stage.

### What does "No local graph for this worktree yet" mean?

This error originates in [`src/graph/vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/vfs-handler.ts) (lines 70-85) when `loadSnapshotOrError` cannot find a JSON snapshot for the current working directory. Run `hivemind graph build` to generate the graph, or `hivemind graph pull` to fetch a pre-built snapshot from remote storage.

### How do I run the graph module unit tests?

Execute `npm test -- tests/shared/graph/vfs-handler.test.ts` to validate the VFS dispatcher and renderer logic. The tests simulate various graph states and verify that `handleGraphVfs` returns the correct results or error codes for malformed paths and missing snapshots.

### Where are graph snapshots stored on disk?

Snapshots are JSON files stored in the `snapshots/` subdirectory of the graph repository directory, which you can locate by running `hivemind graph repo-dir`. The `loadSnapshotOrError` function in [`src/graph/vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/vfs-handler.ts) constructs the full path using `join(baseDir, "snapshots", \`${fileBase}.json\`)`.