Troubleshooting and FAQ

Troubleshooting & FAQ

The app won't launch

• Windows: "unknown publisher" / SmartScreen. Builds are unsigned — click More info → Run anyway. See Installation.
• Windows: nothing happens / window never appears. The desktop shell needs the Microsoft Edge WebView2 runtime. It ships with Windows 10 (1803+) and Windows 11; on a stripped-down machine, install it from Microsoft's WebView2 page.
• macOS: "can't be opened" (Gatekeeper). Right-click the app → Open, or allow it under System Settings → Privacy & Security.

The graph canvas is blank

The canvas is GPU-rendered (Vello over WebGPU). A blank canvas almost always means WebGPU isn't available:

• Web version: use a WebGPU-capable browser — recent Chrome or Edge. Check chrome://gpu for "WebGPU: Hardware accelerated".
• Desktop: the system webview provides WebGPU; make sure your OS/GPU drivers are current.

See Rendering & Performance for how the renderer works.

It pauses / asks me to confirm on a big folder

Above ~3000 files the scan stops and asks you to confirm before running the full analysis — a guard so you don't accidentally analyze something enormous. Confirm to continue. (Pointing it at a folder containing huge vendored trees? It already skips node_modules, build output, .git, and very large files.)

A region of the graph says "layout simplified"

Expected, not an error. When a cluster is too large or too dense for the engine that would ideally lay it out, PolyGraph grids it instead of hanging, and surfaces a small "layout simplified" note (e.g. "Stress → Grid (2 areas)"). On very large graphs this keeps the view responsive. Details: Layout Engine Internals.

A huge repo is slow or won't fully render

PolyGraph collapses files by default and uses level-of-detail so the on-screen element count tracks your viewport rather than the repo size. Tips:

• Stay collapsed and expand files only where you're looking.
• Use filters and the Query Language to isolate a subgraph.
• Switch to package or workspace level for a monorepo overview.

The scaling story (the "Nanite for graphs" LOD work) is in Rendering & Performance.

An edge looks wrong / something's missing

Click the edge to see its evidence (file · line · column) and confidence. References the analyzer couldn't resolve appear in the Problems panel as unresolved or ambiguous findings — that's where to look when an expected edge is absent.

FAQ

Does PolyGraph send my code anywhere? No. Analysis runs locally — the sidecar reads the folder from disk, and source reads are constrained to the scanned root. Nothing is uploaded.

Which languages are supported? 26 — TypeScript/JavaScript via a precise provider, and 25 more via tree-sitter packs. Full list and details: The Graph Model and Language Analysis.

Can I run the checks in CI without the desktop app? Yes — the polygraph check / diff CLI runs the same kernel headlessly. See CLI: Rules & Diff.

Can I script against the graph? Export JSON (see Exports, Workspaces & Editor) or consume the diff --format json payload.

Why is auto-update not available? Builds are unsigned, so auto-update is disabled by design — update from the Releases page.